XMetaL Author 5.1 Enterprise Edition User's Guide

XMetaL Author5.1 EnterpriseEdition User'sGuide

About JustSystems

JustSystems is a leading global software provider with a27-year history of successful innovation in officeproductivity, information management, and consumer andenterprise software. With over 2,500 customers worldwideand annual revenues over $110M, the company iscontinuing a global expansion strategy that includes thelaunch of its new enterprise software offering called xfy(pronounced 'x-fie'), and XMetaL content lifecycle solutions.JustSystems has worldwide office locations including globalheadquarters in Tokyo, Japan, and regional offices in NewYork, NY; London, UK; and Vancouver, Canada. Thecompany currently employs over 1,000 people. Majorstrategic partnerships include IBM, Oracle and EMC. Formore information, please visit http://na.justsystems.com.

Copyright JustSystems Inc. All rights reserved. XMetaL isa registered trademark of JustSystems Canada Inc. Otherproduct names may be trademarks or registeredtrademarks of their respective owners.

XMetaL Author 5.1 Enterprise Edition

12/2007

Contact Information:

Support:North America: +1 866 647 2003Europe: +44 (0) 1753 607 627

Sales:North America: +1 866 793 1542Europe: +44 (0) 1753 607 650International: +1 604 697 8701

Office Locations:

XMetaL Sales & SupportSuite 1800, Two Bentall Centre555 Burrard StreetBox 207Vancouver, BC, CanadaV7X 1M9T: 604-602-9928F: 604-602-9938Toll-Free Sales: 1-866-793-1542

European HeadquartersRegus House, 268 Bath RoadSlough SL1 4DX, United KingdomT: +44 (0) 1753 607 650F: +44 (0) 1753 708 625

US Office1450 Broadway, 39th FloorNew York, NY 10018 USAToll-Free: 1-866-JSI-4-XML

Tokushima Head OfficeBrains Park Kawauchi-choTokushima-city Tokushima 771-0189JapanT: 088 666 1000(+81 88 666 1000 from outside Japan)

Contents

Welcome to XMetaL Author.................................................................................13Sample files...........................................................................................................14Finding information..............................................................................................15Introduction to the user interface.......................................................................17

Document view modes...........................................................................................................17

Normal view.................................................................................................................17

Tags On view...............................................................................................................18

Specify tag and tag text colors....................................................................................18

Specify custom tag and tag text colors........................................................................18

Plain Text view.............................................................................................................19

Page Preview...............................................................................................................19

Select a view...............................................................................................................19

Using the Structure view........................................................................................................20

Open or close the Structure view................................................................................20

Expand all levels of the structure view.........................................................................20

Collapse the structure view to a specific nesting level.................................................20

XMetaL Author panes.............................................................................................................20

Open a pane................................................................................................................21

Undock a pane............................................................................................................21

Redock a floating pane................................................................................................21

Full-screen mode....................................................................................................................21

Enable full-screen mode.........................................................................................................21

Workbook mode.....................................................................................................................22

Enable workbook mode..........................................................................................................22

Workspaces............................................................................................................................22

Create a workspace.....................................................................................................22

Open a workspace.......................................................................................................22

Toolbars..................................................................................................................................23

Standard toolbar..........................................................................................................23

Formatting toolbar.......................................................................................................24

Table toolbar................................................................................................................25

Table Advanced toolbar...............................................................................................26

Macros toolbar.............................................................................................................26

Preview toolbar............................................................................................................26

Associate a blank Preview toolbar button with a Web browser....................................27

Remove associated Web browser from Preview toolbar.............................................27

Views toolbar...............................................................................................................27

Special Characters and Symbols toolbars...................................................................28

Reviewing toolbar........................................................................................................28

Working with XML and SGML..............................................................................29

XMetaL | Contents | 3

DTDs, Schemas, and rules files.............................................................................................30

Valid and well-formed markup................................................................................................31

Validate a document....................................................................................................32

Working without rules checking...................................................................................32

DOCTYPE declarations..........................................................................................................33

Internal subset........................................................................................................................34

Character encoding and Unicode support..............................................................................35

Opening and saving documents with Unicode encoding.............................................36

Rules for opening XML documents with Unicode encoding........................................36

Rules for saving XML documents with Unicode encoding...........................................36

Rules for opening SGML documents with Unicode encoding.....................................37

Rules for saving SGML documents with Unicode encoding........................................37

Inserting comments................................................................................................................37

Insert a text comment.............................................................................................................37

CDATA sections......................................................................................................................38

Insert a CDATA section...........................................................................................................38

Marked sections.....................................................................................................................38

Marked section parameters.........................................................................................38

Result parameters.......................................................................................................39

Restrictions on marked section parameters................................................................40

Insert a marked section...............................................................................................40

Entities and special characters...............................................................................................41

Entity naming conventions...........................................................................................41

Creating and editing text entities.................................................................................42

Text entity content types..............................................................................................42

Creating and editing graphic entities...........................................................................42

Creating and editing external entities..........................................................................43

Creating and editing parameter entities in SGML documents.....................................43

Create an entity...........................................................................................................43

Change an entity.........................................................................................................44

Delete an entity............................................................................................................44

Inserting general entity references..............................................................................44

Insert an entity reference.............................................................................................44

Typing special characters and symbols.......................................................................45

Enter a special character or symbol............................................................................45

Converting between entities and characters...............................................................45

Working with elements.........................................................................................46Inserting elements..................................................................................................................46

Insert an element...................................................................................................................47

Change an element................................................................................................................47

Splitting elements...................................................................................................................47

Split an element......................................................................................................................47

Join two adjacent elements....................................................................................................48

Remove elements...................................................................................................................48

Remove tags..........................................................................................................................48

4 | XMetaL | Contents

Working with attributes........................................................................................49Edit an attribute......................................................................................................................50

Working with files.................................................................................................51Creating a new document......................................................................................................51

Create a document from a template............................................................................51

Create a blank document ...........................................................................................51

Opening documents...............................................................................................................51

Open a file...................................................................................................................52

Open an XML file displayed in a browser....................................................................52

What to do if the DTD, Schema, or rules file cannot be found.....................................52

Opening files in WebDAV-enabled folders...................................................................53

Opening external file entities.......................................................................................53

Saving documents..................................................................................................................53

Save a document.........................................................................................................54

Save a document to a different filename or location....................................................54

Save all open documents............................................................................................54

Closing documents.................................................................................................................54

Close a document........................................................................................................54

Close all open documents...........................................................................................55

Moving between open documents..........................................................................................55

Move between documents...........................................................................................55

Editing well-formed XML documents......................................................................................55

Create a well-formed XML document..........................................................................56

Define an element.......................................................................................................56

Define an attribute.......................................................................................................56

Printing documents.................................................................................................................57

Print a document.........................................................................................................57

Print from a browser....................................................................................................57

Selecting and editing text....................................................................................58Selecting text..........................................................................................................................58

Editing selections...................................................................................................................59

Copy and paste a selection....................................................................................................59

Move a selection.....................................................................................................................59

Delete a selection...................................................................................................................60

Finding and replacing text...................................................................................61Searching for text...................................................................................................................61

Find and replace text...................................................................................................61

Find and replace text within a specified element.........................................................62

Find and replace text with an entity reference.............................................................62

Repeat the last search.................................................................................................62

Searching for elements..........................................................................................................62

Find and replace elements.....................................................................................................63

Searching for entities..............................................................................................................63

Find and replace an entity reference...........................................................................64


Find and replace an entity reference with text.............................................................64

Using search patterns............................................................................................................64

Search pattern summary........................................................................................................65

Working with lists.................................................................................................67Insert a list..............................................................................................................................67

Insert a list item......................................................................................................................67

Insert a list within a list...........................................................................................................67

Convert existing list items to a nested list...............................................................................68

Convert paragraphs to a list...................................................................................................68

Convert list items to paragraphs ............................................................................................68

Convert one type of list to another.........................................................................................68

Definition lists.........................................................................................................................68

Working with images............................................................................................70Insert an image......................................................................................................................70

Insert a figure with a title........................................................................................................71

Insert an image represented by an entity...............................................................................71

Edit image properties.............................................................................................................71

Displaying images..................................................................................................................71

Working with tables..............................................................................................73HTML tables...........................................................................................................................73

HTML table properties.................................................................................................74

Insert a table caption...................................................................................................74

Edit a table caption......................................................................................................75

CALS tables...........................................................................................................................75

CALS table properties.................................................................................................75

Proportional column widths.........................................................................................76

Insert a table..........................................................................................................................76

Format a table........................................................................................................................76

Format a column....................................................................................................................77

Format a row..........................................................................................................................77

Format a cell...........................................................................................................................77

Format a selection of cells......................................................................................................77

Navigating within a table.........................................................................................................78

Enter a tab character in a table cell........................................................................................78

Editing table rows and columns..............................................................................................78

Insert rows or columns................................................................................................79

Delete a row from a table............................................................................................79

Delete columns from a table........................................................................................79

Move a table row or column.........................................................................................79

Resizing rows and columns....................................................................................................79

Change the height of a row.........................................................................................79

Change the width of a column.....................................................................................80

Editing table cells...................................................................................................................80

Split a cell vertically.....................................................................................................80


Split a cell into two rows..............................................................................................80

Merge adjacent cells....................................................................................................80

Contract a cell spanning two or more rows or columns...............................................80

Moving and copying table cells...............................................................................................81

Move a block of cells...................................................................................................81

Copy a block of cells....................................................................................................81

Inserting tables from other applications.................................................................................82

Marking changes to text.......................................................................................83Track changes........................................................................................................................83

Move between tracked changes.............................................................................................84

Accepting or rejecting tracked changes..................................................................................84

Accept or reject tracked changes...........................................................................................84

Using the writing tools.........................................................................................85Checking your spelling...........................................................................................................85

Check spelling.............................................................................................................85

Ignore a flagged word..................................................................................................85

Using spell checker word lists................................................................................................86

Working with main word lists..................................................................................................86

Add a main word list....................................................................................................86

Remove a main word list.............................................................................................86

Working with user word lists...................................................................................................86

Set the default user word list.......................................................................................87

Add a user word list.....................................................................................................87

Add an entry to a user word list...................................................................................87

Delete an entry from a user word list...........................................................................87

Change the replacement text for an entry in a user word list......................................88

Change an entry in a user word list.............................................................................88

Using the thesaurus...............................................................................................................88

Look up a word in the thesaurus.................................................................................88

Replace a word using the thesaurus...........................................................................89

Insert a word from the thesaurus.................................................................................89

Set thesaurus options..................................................................................................89

Set thesaurus look-up options.....................................................................................90

Set the thesaurus data file...........................................................................................90

Specifying the language settings............................................................................................91

Set the language.........................................................................................................91

Add a language...........................................................................................................91

Remove a language.....................................................................................................91

Setting spell checker options..................................................................................................92

Setting thesaurus options ......................................................................................................92

Using macros........................................................................................................94Restrictions on macros...........................................................................................................94

Running macros.....................................................................................................................94

Run a macro...........................................................................................................................95


Recording macros..................................................................................................................95

Record a macro......................................................................................................................95

Setting up macro access shortcuts........................................................................................96

Set the keyboard shortcut for a macro........................................................................96

Associate a macro with a toolbar button......................................................................96

Associate a macro with a menu command..................................................................96

Deleting macros.....................................................................................................................97

Delete a macro.......................................................................................................................97

Using the Resource Manager..............................................................................98Assets tab...............................................................................................................................98

Desktop tab............................................................................................................................98

Inserting objects in your document........................................................................................99

Insert an asset from an asset folder............................................................................99

Insert an object from your system...............................................................................99

Creating an asset collection...................................................................................................99

Create an asset folder.................................................................................................99

Rename an asset folder............................................................................................100

Add an asset to the My Assets folder........................................................................100

Importing databases..........................................................................................101Import a database................................................................................................................101

Choosing a database...........................................................................................................101

Open a database file or folder..............................................................................................102

Open a Data Source Name..................................................................................................102

Choosing fields and setting their order.................................................................................102

Add fields to a query..................................................................................................102

Remove fields from a query.......................................................................................102

Editing a field........................................................................................................................103

Edit field properties..............................................................................................................103

Formatting table and element output....................................................................................103

Configure the output table.........................................................................................104

Change an element name.........................................................................................104

Table joins............................................................................................................................104

Ceate a joined table query.........................................................................................105

Remove a table join...................................................................................................105

Update a table......................................................................................................................105

Customizing XMetaL Author..............................................................................106Customizing environments for multiple users.......................................................................106

Creating templates...............................................................................................................107

Create a template.................................................................................................................107

Creating custom toolbars and menus...................................................................................108

Create a toolbar.........................................................................................................108

Associate a button with a macro................................................................................109

Create a menu...........................................................................................................109

Associate a menu with a macro.................................................................................109


Setting options......................................................................................................................110

Setting DITA options.............................................................................................................111

Setting a filename prefix.......................................................................................................112

Keyboard shortcuts............................................................................................113File commands ....................................................................................................................113

Editing commands................................................................................................................113

Switching between views and display modes ......................................................................114

Inserting, deleting, and moving text and markup .................................................................114

List formatting.......................................................................................................................115

Moving around in a document .............................................................................................115

Moving around in tables ......................................................................................................116

Making and extending selections in a document..................................................................116

Making and extending cell selections in a table...................................................................117

Choosing menu commands .................................................................................................117

Moving between panes, documents, and dialog boxes........................................................117

Navigating in a dialog box ...................................................................................................118

Introduction to DITA...........................................................................................119Topics...................................................................................................................................119

Topic structure......................................................................................................................120

Maps.....................................................................................................................................121

Relationship tables...............................................................................................................121

DITA references....................................................................................................................122

Authoring DITA content......................................................................................123Create a topic.......................................................................................................................123

Insert a section.....................................................................................................................123

Insert a subtopic...................................................................................................................123

Insert a paragraph................................................................................................................124

Insert an element.................................................................................................................124

Insert an inline element........................................................................................................124

Insert a multimedia object....................................................................................................125

Insert a list of steps..............................................................................................................125

Insert a step component.......................................................................................................125

Creating cross-references and related links.........................................................................125

Insert a cross-reference.............................................................................................126

Insert a related link....................................................................................................126

Refresh references...............................................................................................................127

Insert topic metadata............................................................................................................127

Promote or demote a topic...................................................................................................127

Editing properties.................................................................................................................128

Creating indexes...................................................................................................................128

Insert an index marker..........................................................................................................129

Re-using content................................................................................................131Displaying reusable content.................................................................................................132

Generalizing elements with content references....................................................................133


Create a reusable component..............................................................................................133

Insert a reusable component................................................................................................134

Insert an element with a content reference..........................................................................134

Attach a content reference to an element............................................................................135

Working with DITA maps....................................................................................136Create a map........................................................................................................................136

Create and insert a topic......................................................................................................137

Insert an existing topic..........................................................................................................137

Insert a topic group..............................................................................................................137

Insert a reference to a non-DITA file.....................................................................................137

Insert a Web link...................................................................................................................137

Insert a map reference.........................................................................................................138

Insert an Eclipse navigation reference.................................................................................138

Insert a topic heading...........................................................................................................138

Insert a relationship table.....................................................................................................138

Edit a map in the Map Editor................................................................................................138

Edit a map in XML view........................................................................................................139

Working with DITA bookmaps...........................................................................140Create a bookmap................................................................................................................140

Insert bookmap metadata....................................................................................................140

Insert an existing component...............................................................................................140

Open a component...............................................................................................................141

Create and insert a chapter, appendix, or part.....................................................................141

Insert front or back matter....................................................................................................141

Create and insert a special topic..........................................................................................141

Create and insert a booklist.................................................................................................141

Create and insert a glossary................................................................................................142

Publishing documents.......................................................................................143XMetaL Enhanced deliverable types....................................................................................144

DITA Open Toolkit.................................................................................................................145

Upgrade to a newer version of the DITA Open Toolkit .........................................................145

Advanced options.................................................................................................................145

Specifying a language..........................................................................................................146

Chunking..............................................................................................................................146

Set chunking.........................................................................................................................147

Viewing online Help output...................................................................................................147

Create a deliverable type......................................................................................................147

Edit a deliverable type..........................................................................................................148

Set preview options..............................................................................................................148

Generate output...................................................................................................................148

Extending your publishing options........................................................................................148

Publishing configuration files.....................................................................................150

Specifying parameters...............................................................................................150

Creating and modifying output formats......................................................................152


Create an output format.............................................................................................152

Modify an output format.............................................................................................152

Troubleshooting....................................................................................................................153

Working with conditions....................................................................................154Apply a condition..................................................................................................................155

Display conditions in previews or output..............................................................................155

Style a condition...................................................................................................................155

Modify conditions..................................................................................................................156

Working with DITA specializations....................................................................157Configure XMetaL................................................................................................................157

Create a template.................................................................................................................158

Apply custom formatting.......................................................................................................159

Create a customized XMetaL form.......................................................................................159

Generate IDs for PDF output................................................................................................159

Overriding base formatting ..................................................................................................159

Working with a content repository....................................................................161Open a repository map or topic file......................................................................................161

Create a new repository file..................................................................................................162

Create a new repository map...............................................................................................162

Repository toolbar................................................................................................................162

Adapter configuration file......................................................................................................163

Working with XMetaL Reviewer comments......................................................164Find comments.....................................................................................................................164

Filter comments....................................................................................................................164

Integrate revisions................................................................................................................164

Change comment status......................................................................................................164

Remove all comments..........................................................................................................164

Appendix A: Configuring XHTML and CHM output.........................................165Creating custom CSS files...................................................................................................165

Headers and footers.............................................................................................................166

Deliverable types and parameters........................................................................................167

Save settings in an XHTML deliverable type........................................................................167

Save settings in a CHM deliverable type..............................................................................170

Appendix B: Configuring PDF output...............................................................173Custom configuration framework..........................................................................................173

Before you begin..................................................................................................................174

Page layouts.........................................................................................................................175

Attribute sets..............................................................................................................175

Page masters.............................................................................................................176

Headers and footers.............................................................................................................177

Attribute sets..............................................................................................................177

Variables....................................................................................................................177

XSL templates...........................................................................................................178

Page body content...............................................................................................................180


Notes....................................................................................................................................182

Front matter..........................................................................................................................183

Fonts....................................................................................................................................184

Localization..........................................................................................................................184

Debugging your custom configuration..................................................................................184

PDF parameters...................................................................................................................184

Page margins.............................................................................................................185

Headers and footers..................................................................................................186

Fonts..........................................................................................................................187

Tables........................................................................................................................188

Glossary..............................................................................................................189


Welcome to XMetaL Author

XMetaL Author is a graphical editor for creating and editing XML and SGML documents. It provides authorswith a familiar word processing environment and a rich array of powerful authoring aids including multipledocument views and context-sensitive property inspectors.

The user interface features configurable window management, customizable toolbars, and tear-off menus.The Resource Manager provides drag and drop management of boilerplate text, document fragments, images,and other assets, both locally and across a network.

In order to integrate XMetaL Author into your organization’s workflow and business processes, you may findthat you need to perform some customization of the product. If you have any questions about customizations,contact your system administrator.

Send your comments or questions about XMetaL documentation to [email protected].

XMetaL | Welcome to XMetaL Author | 13

Sample files

Sample files demonstrating various aspects of XMetaL Author functionality are installed in the Samples folder,..\XMetaL\Author\Samples.

It is recommended that you copy these files and work on them in your own work area.

A sample DITA map file is available through the Help menu when a DITA topic file is open.

14 | XMetaL | Sample files

Finding information

There are several different ways to find information about XMetaL Author:

• Help buttons. Most dialog boxes have Help buttons that take you directly to the appropriate topic.

• Tip of the Day. Displays a tip about using XMetaL Author on startup. This feature can be disabled byclearing the Show Tips on Startup option.You can display a tip at any time by choosing Tip of the Day fromthe Help menu.

• Release notes. The latest release information is available from the XMetaL Author program group.

Other sources

You are encouraged to consult the many available printed and online XML references including those listedbelow.

• The Extensible Markup Language (XML) 1.0 (Fourth Edition) (a W3C Recommendation), available atwww.w3.org/TR/REC-xml

• The XML Handbook by Charles Goldfarb and Paul Prescod, at www.xmlhandbook.com

• The Annotated XML Specification by Tim Bray, at www.xml.com/axml/testaxml.htm

• XML-related publications, events, and software, from the World Wide Web Consortium web site atwww.w3.org/XML

• XML.com

• The SGML/XML Web Page (maintained by Robin Cover) at www.oasis-open.org/cover/sgml-xml.html providesa reference database

• The XML Companion by Neil Bradley is recommended for beginners (see also www.bradley.co.uk)

• XML Specification Guide by Ian Graham and Liam Quin is a comprehensive reference book (see alsowww.wiley.com/compbooks/graham-quin)

• XML: The Annotated Specification by Bob DuCharme is recommended for advanced users

• The Project Cool Developer Zone at http://www.devx.com/projectcool/developer/ provides references onvarious technologies, including XML

• XML by Example by Benoit Marchal is recommended for intermediate-level Web developers

• XML Black Book by Natanya Pitts-Moultis and Cheryl Kirk is recommended for intermediate to advancedwebmasters and Web developers

• XML Pocket Reference by Robert Eckstein, a reference for XML, XSL, and XLL

DITA

You can find other information about DITA from the sources listed below.

• dita.xml.org

• Introduction to the Darwin Information Typing Architecture and other DITA-related publications from IBMdeveloperWorks at http://www.ibm.com/developerworks/

• Organization for the Advancement of Structured Information Standards (OASIS) at http://docs.oasis-open.org

• DITA Open Toolkit 1.3.1 Documentation Package from VR Communications at http://www.vrcommunica-tions.com/resources.htm

• xmetal-dita and dita-users user groups on yahoo.com

XMetaL | Finding information | 15

• The DITA Open Toolkit project at http://dita-ot.sourceforge.net for the latest versions of the DITA OpenToolkit User Guide and other publications

16 | XMetaL | Finding information

Introduction to the user interface

The XMetaL Author interface is highly customizable. This topic, and this online help in general, explain theinterface and default (non-customized) functionality. The version you are using may differ because of cus-tomization. If XMetaL Author has been customized at your site, there may be a person responsible for cus-tomization whom you can consult, or even a customized version of this documentation.

The interface has these components:

• Menus

• Toolbars

• The main document pane, which shows different editing views

• The Structure View pane

• The context bar

• Additional panes that open when certain functions are invoked, such as the Attribute Inspector and ElementList panes.

Note: The information provided here explains the interface and default (non-customized) functionality.If you are using a customized version of XMetaL Author, consult your customizer for details.

Document view modes

XMetaL Author provides you with different ways to display your documents, depending on how you want towork with them.The three working views differ mostly in how much of the XML markup they display.Therefore,to understand the views, you need to have some knowledge of XML and SGML.

The view modes are:

• Normal. In Normal view, your document appears much as it would appear in a word processor, that is,without visible XML or SGML markup.You see only the content of your document. A Cascading Style Sheetcontrols the formatting. For example, headings can be larger than body text, certain kinds of text can bebold or italicized, list items can be indented, and so on.

• Tags On. Element start and end tags are visible. Appearance is determined by a Cascading Style Sheet.

• Plain Text. There is no content formatting. All markup is visible, including DOCTYPE and entity declarations.The different types of markup are differentiated by color.

• Page Preview. Your document is displayed as it would appear in a Web browser. This is a view-only mode.

Normal view

Normal view displays documents as they would appear in a word processor. The display can include imagesand tables. Structured editing commands are available from the menus; you need not be concerned aboutthe details of the markup. XMetaL ensures that the content you create is valid.

A number of DTD-specific customizations may have been made in order to enhance the capabilities of theNormal view. Because these customizations are site-specific, the exact capabilities of Normal view editing

XMetaL | Introduction to the user interface | 17

vary. If the Normal view is properly configured, it is easy and convenient to edit documents in this view. Someediting techniques commonly available in the Normal view are listed below.

• You can specify an element to follow an element. For example, pressing Enter at the end of a Title elementcould insert a paragraph element.

• If the selection or insertion point is inside a sequence of nested block elements, pressing Enter repeatedlymoves the insertion point up the hierarchy of nested elements.

• Follow the prompts in the replacement text that is displayed when you create an element.

• Clicking to the right of a table moves the insertion point outside of the table.This is particularly useful whenthe table is at the bottom of the document.

• If you are editing a <pre>-like element (one in which whitespace is preserved), press Enter to insert a linebreak, and Shift + Enter to close the element and start a new paragraph.

• To see the context of the current element, check the context bar to the left of the horizontal scrollbar.

• If you want to change an element, make a selection from the dropdown list in the Formatting toolbar.

Tags On view

Tags On view shows element start and end tags. It is not an exact representation of the markup. Tags Onview is useful for navigating the element hierarchy and for accurate positioning of the insertion point. Thecomplete set of structured editing commands is available in Tags On view.

You can select an entire element by clicking its start or end tag.

You can collapse or expand tags through the right-click menu.

You can specify colors for your tags and tag text.

When you rest the mouse cursor on a tag, a tag tip appears, displaying all set attributes.

Specify tag and tag text colors

1. Open a document and switch to Tags On view.

2. Click Tools ➤ Options and select the View tab.

3. Click one of the following:

• Foreground (for tag text)• Background (for tag background)

4. Click the desired color in the Browser Safe Palette.

Specify custom tag and tag text colors

1. Open a document and switch to Tags On view.

2. Click Tools ➤ Options and select the View tab.

3. Click one of the following:

• Foreground (for tag text)• Background (for tag background)

4. In the Custom Palette area, click the New Custom Palette button and type a name.

5. In the Color to Use area, specify a color value.

18 | XMetaL | Introduction to the user interface

6. Click the Add Color to Custom Palette button button.

Plain Text view

You can use Plain Text view to display the XML or SGML markup in your document. In Plain Text view, theDOCTYPE declaration is visible at the top of the file. This declaration specifies a DTD, a file that describesthe allowable sequences of elements and attributes. Since context-sensitive rules checking is not active inPlain Text view, XMetaL Author does not prevent you from entering invalid markup. However, you can stillvalidate your document.

To differentiate between the different types of markup, Plain Text view is color-coded.The markup is organizedand displayed in different colors so that you can easily identify elements, attributes, and text. By default,elements are red, attributes are blue, and text is black.

In Plain Text view, line numbers are displayed on the left side of the pane. If a line is longer than the currentwidth of the document pane, it wraps to the next line. This is referred to as soft wrapping.

You can set colors and line wrapping options through the Options dialog box.

Block elements can be indented (“pretty printing”) for easier reading.You can indent or outdent blocks ofselected text in Plain Text view by pressing Tab or Shift + Tab.

Note: Not all commands are available in Plain Text view. For the complete set of commands, switch toNormal or Tags On view.

Page Preview

In Page Preview, you can display XML documents as they would appear in a Web browser.You can performany browser tasks, including navigating to links. By right-clicking your document, you can bring up a menufrom which you can perform actions such as moving backward or forward, saving an image as wallpaper,and viewing the properties of the document.

If a Cascading Style Sheet is linked to the document, the browser formats the document according to thatstyle sheet.

Tip: You can also preview a document and add or delete a browser by choosing File ➤ Preview inBrowser.

Select a view

1. Click View and select one of the following:

• Normal• Tags On• Plain Text• Page Preview


Using the Structure view

The Structure view displays the outline or information hierarchy of the document. Block elements are displayedone per line, and indented to indicate their nesting level. Each open document has its own structure view.

The Structure view inherits the styles of the main document. In addition, it has its own style sheet for eachDTD that you use. Depending on how the structure view style sheet has been set up, elements that have

block sub-elements may be represented by (book) icons. Click these icons to expand or collapse their

elements. Elements that have no block sub-elements may be represented by (page) icons.

Block elements can also be represented by start tag icons in the structure view. If start tag icons are displayed,tool tips above these icons display the elements’ attributes, just as in Tags On view.

In the structure view you can insert, cut, paste, copy, and drag-and-drop elements. The selections in thestructure view and main document view are synchronized.

You can also collapse and expand the Structure view using commands on the right-click menu.

Tip: The structure view is represented by a vertical bar at the left end of the group in the lower left cornerof the document pane. Dragging this bar to the left or right hides, shows, or resizes the structure view.

Open or close the Structure view

1. Click View ➤ Structure View.

Expand all levels of the structure view

1. Right-click anywhere in the structure view.

2. Click Expand All.

Collapse the structure view to a specific nesting level

1. Right-click anywhere in the structure view.

2. Point to Collapse at Level, and then click the desired level.

XMetaL Author panes

You can have one or more panes open in your work area at a particular time:

• Attribute Inspector. Enables you to edit attributes.

• Element List. Enables you to insert elements in your document.

• Resource Manager. A file management tool that gives you access to all kinds of objects: images, cascadingstyle sheets, scripts, etc., and lets you perform “intelligent insertion” of these objects.

Docked and floating panes


XMetaL Author panes can be customized and moved. When you first display a pane such as the AttributeInspector, it is docked (attached) to the work area border. If you want to turn the pane into a floating panethat you can move anywhere on your screen, you undock the pane.

Open a pane

1. Click View and select one of the following:

• Attribute Inspector• Element List• Resource Manager

Undock a pane

1. Do one of the following:

• Double-click the title bar at the top of the pane.

• Click and hold the title bar at the top of the pane and drag the pane away from its docked position.• Right-click the title bar at the top of the pane. Click Allow Docking to turn off the option.

Redock a floating pane

1. Right-click anywhere in the pane except the border or title bar.

2. Ensure Allow Docking is enabled (checked).


• Double-click the title bar.• Right-click the title bar. In the menu that appears, click Redock.• Drag the pane to the side of the window to which you want to anchor the pane.

Full-screen mode

You can use the full-screen mode to display your current document in the entire viewing space of your monitor.

When you use full-screen mode, XMetaL Author expands to fill the screen if it was not already maximized,with only the menu bar and the full-screen toolbar button visible. Other panes such as the Structure View andthe Resource Manager can also be made visible in full screen mode since it has its own workspace. The full-screen view and toolbar configuration are remembered the next time you enter this mode.

You can toggle between full-screen mode and normal display through the View menu.

Enable full-screen mode

1. Click View ➤ Full Screen.


You can repeat this step to disable full-screen mode.

Workbook mode

Workbook mode enables you to access multiple documents quickly and easily by using tabs at the bottomof each document.

Enable workbook mode

1. Click View ➤ Workbook Mode.

2. Click the tab for the document that you want to view.

Workspaces

A workspace refers to the current state of an XMetaL Author session, including which files are open, whichpanes and toolbars are visible, whether panes are floating or docked, and pane positions. When you save aa workspace, this current-state information is saved. The most recently saved workspace is opened the nexttime you start XMetaL Author.

Workspace information is saved on a user-by-user basis and is saved to the Windows registry.

Create a workspaceYou can save a maximum of eight workspaces. If you try to save a ninth workspace, the oldest workspaceis deleted.

1. Click File ➤ Workspace ➤ Manage.

2. Click New .

3. Type a name for your workspace, and then press Enter.

4. Click Yes to save the workspace.

Open a workspace

1. Click File ➤ Workspace ➤ Manage.

2. Select the workspace that you want to open.

3. Click Open.


Toolbars

You can access commands by clicking the buttons on the toolbars. Tooltips (short descriptions of what thetoolbar buttons do) appear near the buttons when you hover the cursor over them.

When you open XMetaL Author for the first time, the Standard and Formatting toolbars are displayed.

Using the Toolbars command on the View menu, you can show/hide toolbars, create new toolbars, or modifyexisting toolbars.

Standard toolbar

Note: Your installation of XMetaL Author might not include all of these buttons. It might also includebuttons not listed here. See your customizer for more information.

DescriptionMenu commandKeyboard shortcutName/TooltipButton Icon

Opens the New dialogbox or opens a new

File ➤ NewCtrl + NNew Page

document based onthe default template.

Opens the Open dialogbox, from which you

File ➤ OpenCtrl + OOpen

can open an existingdocument.

Saves the active doc-ument.

File ➤ SaveCtrl + SSave

Saves all open docu-ments.

File ➤ Save AllCtrl + QSave All

Opens the Find andReplace dialog box.

Edit ➤ Find andReplace

Ctrl + FFind and Replace

Finds the next occur-rence of the text string

Edit ➤ Find NextF3Find Next

in the Find field of theFind and Replacedialog box.

Opens the WritingTools dialog box to theSpell Checker page.

Tools ➤ SpellChecker

F7Check Spelling

Removes the selectedtext or element(s) tothe Windows clipboard.

Edit ➤ CutCtrl + XCut

Copies the selectedtext or element(s) tothe Windows clipboard.

Edit ➤ CopyCtrl + CCopy

Pastes the contents ofthe clipboard.

Edit ➤ PasteCtrl + VPaste

Reverses the lastaction.

Edit ➤ UndoCtrl + ZUndo

Redoes the lastreversed action.

Edit ➤ RedoCtrl + YRedo


Inserts an imageelement.

Insert ➤ Image-Insert Image

Inserts a table elementand all required childelements.

Table ➤ Insert Table-Insert Table

Opens the ElementList.

Insert ➤ ElementCtrl + Shift + IInsert Element

Opens or closes theResource Managerpane (toggle action).

View ➤ ResourceManager

-Resource Manager

Makes the previousdocument in the list of

Window ➤ PreviousAlt + Left ArrowPrevious Document

open documents theactive document.

Makes the next doc-ument in the list of

Window ➤ NextAlt + Right ArrowNext Document

open documents theactive document.

Checks the active doc-ument for well-

Tools ➤ ValidateDocument

F9Validate Document

formedness andvalidity.

Opens the XMetaLAuthor online Help.

Help ➤ ContentsF1Help Contents

Formatting toolbar


DescriptionKeyboard ShortcutName/TooltipButton Icon

Lists the elements that canbe inserted at the cursorlocation.

—Style Element

Applies or inserts an elementdesignated as bold.

Ctrl + BBold

Applies or inserts an elementdesignated as italic.

Ctrl + IItalics

Applies or inserts an elementdesignated as underscore.

Ctrl + UUnderscore

Inserts an element desig-nated as an ordered (num-bered) list.

—Numbered List

Inserts an element desig-nated as an unordered (bul-leted) list.

—Bulleted List


Table toolbar


DescriptionMenu commandName/TooltipButton Icon

Opens the Insert Tabledialog box.

Table ➤ Insert TableInsert Table

Opens the Table Propertiesdialog box.

Table ➤ Table PropertiesEdit Table Properties

Adds an empty row abovethe current row.

Table ➤ Insert Rows orColumns

Insert Row Above

Adds an empty row belowthe current row.

Insert Row Below

Deletes the current row,including any elements andtext in the row.

Table ➤ Delete RowDelete Row

Adds an empty column to theleft of the current column.

Table ➤ Insert Rows orColumns

Insert Column Left

Adds an empty column to theright of the current column.

Insert Column Right

Deletes the current column,including any elements andtext in the column.

Table ➤ Delete ColumnDelete Column

Moves the current row upone row.

Table ➤ Move Row orColumn

Move Row Up

Moves the current row downone row.

Move Row Down

Moves the current column tothe left by one column.

Move Column Left

Moves the current column tothe right by one column.

Move Column Right

Merges the current cell withthe cell to the right of it.

Table ➤ Merge CellMerge Cell Right

Merges the current cell withthe cell to the left of it.

Merge Cell Left

Merges the current cell withthe cell above it.

Merge Cell Up

Merges the current cell withthe cell below it.

Merge Cell Down

Splits the current cell into twocells horizontally.

Table ➤ Split Cell intoRows

Split Cell into Rows

Splits the current cell into twocells vertically.

Table ➤ Split Cell intoColumns

Split Cell into Columns


Table Advanced toolbar

The Table Advanced buttons are only available when the cursor is located in a table cell that spans at leasttwo rows, at least two columns, or both.


DescriptionName/TooltipButton Icon

Inserts an empty cell to the left of theactive cell, decreasing the size of theactive cell.

Contract Cell from Left

Inserts an empty cell to the right of theactive cell, decreasing the size of theactive cell.

Contract Cell from Right

Inserts an empty cell below the activecell, decreasing the size of the activecell.

Contract Cell from Bottom

Inserts an empty cell above the activecell, decreasing the size of the activecell.

Contract Cell from Top

Macros toolbar



Runs the macro selected inthe Select Current Macro list.

Tools ➤ Macros to open theMacros dialog box. (You canperform both of these func-

Run Current Macro

Shows the currently selectedmacro. Click the arrow button

Select Current Macro tions from the Macros dialogbox.)

to select a new macro fromthe list.

Records all keystrokes as anew macro.

Tools ➤ Record NewMacro

Record Macro

Stops recording keystrokesto the new macro.

Tools ➤ Stop RecordingStop Recording

Opens the Macros dialogbox.

Tools ➤ MacrosMacros

Preview toolbar

You use the buttons on the Preview toolbar to display your document in a browser. The default browswer isMicrosoft Internet Explorer. The default toolbar also has blank buttons that you can program to open otherinstalled browsers.


Associate a blank Preview toolbar button with a Web browser

1. Open a document.

2. Ensure that the Preview toolbar is visible (if necessary, right-click in the toolbar area and click Previewon the menu that appears).

3. Click the blank Preview button that you want to associate with a browser.

4. Find and click the executable (.exe) file for the browser.

5. Click Open.

Remove associated Web browser from Preview toolbar

1. Open a document.

2. Click File ➤ Preview in Browser.

3. Select a browser.

4. Click Delete.

Views toolbar


DescriptionMenu commandKeyboard shortcutName/TooltipButton Icon

Displays the activedocument in Plain Textview.

View ➤ Plain TextCtrl + Shift + HPlain Text

Displays the activedocument in Tags Onview.

View ➤ Tags OnCtrl + Shift + OTags On

Displays the activedocument in Normalview.

View ➤ NormalCtrl + Shift + WNormal

Displays the activedocument in abrowser.

View ➤ Page PreviewCtrl + Shift + VBrowse

Opens and closes theAttribute Inspector.

View ➤ AttributeInspector

Shift + F6Attribute Inspector

Opens and closes theElement List.

View ➤ Element List-Insert Element Window

Opens and closes theResource Manager(toggle action).

View ➤ ResourceManager

-Resource Manager

Toggles between dis-playing the active doc-

View ➤ Full Screen-Full screen

ument in full screenmode and in normalwindow mode.


Special Characters and Symbols toolbars

The Special Characters toolbar contains accented (Roman) letters and other characters that are used invarious European languages but that do not have corresponding keys on US English keyboard layouts. TheSymbols toolbar contains special symbols such as additional punctuation characters, currency symbols, mathsymbols, and others. When you click a button on the Special Characters or Symbols toolbar, the characteris inserted in your XMetaL Author document. Depending on the encoding of your document, it may be insertedas an entity reference or as an actual character.

Reviewing toolbar



Turns change tracking on oroff (toggle action).

Tools ➤ Track ChangesTrack Changes

Goes to and selects the pre-vious tracked change in thedocument.

-Previous Change

Goes to and selects the nexttracked change in the doc-ument.

-Next Change

Accepts the currentlyselected change.

-Accept Change

Rejects the currentlyselected change.

-Reject Change

Opens the Accept or RejectChanges dialog box.

Tools ➤ Accept or RejectChanges

Accept or Reject Changes

Shows the Revision MarkOptions tab.

Tools ➤ Options, click theChange Tracking tab

Revision Mark Options


Working with XML and SGML

This set of topics introduces XML and SGML, discusses some of the differences between the two, anddescribes how to use XMetaL Author to create XML and SGML elements, attributes, and entities.

If you use XMetaL Author in Normal view, you do not need to have a complete understanding of XML orSGML. But the more you work with your documents, the more likely you are to want to add something thatrequires some knowledge of these standards.

SGML (Standardized General Markup Language) is a document processing standard defined by the WorldWide Web Consortium (W3C). XML (Extensible Markup Language) is a form of SGML. Like HTML, bothSGML and XML are used to “mark up” documents for structure and format. XML and SGML are much moreflexible than HTML, however, because with them, you can create and format your own markup according toyour needs. This makes them much more powerful tools than HTML, especially for complex document typesand data storage and processing.

Here is a list of the main differences between XML and SGML:

• All XML documents start with a processing instruction (called the XML declaration) that indicates that thefile is an XML file: <?xml version="1.0"?>

• Empty elements in XML are marked up in the form <TAGNAME/>, whereas empty elements in SGML aremarked up in the form <TAGNAME>.

• SGML files can have several types of marked sections, whereas XML files can have only CDATA sections.No SDATA entities are allowed in XML.

• In XML, start- and end-tags can never be omitted as they can with some SGML DTDs.

• In XML, start- and end-tags cannot be minimized (for example, </> ).

• In XML, attribute values must be surrounded by single or double quotes.

• In XML, entity references must always be terminated with a semicolon (;).

• In XML, element and attribute names are case-sensitive.

• External identifiers in XML must contain a system identifier, and that identifier is interpreted as a URL.

• There is Schema support for XML files only. Document and data structure are described by Schemas,freeing up authors from having to keep track of the terms in which data is exchanged.

All syntactic requirements of SGML and XML are met by files created in XMetaL Author. All files saved withXMetaL Author are well-formed and normalized.

The structure of an XML document is determined by a DTD or Schema, which specifies which elements theXML document can (and, for some elements, must) contain, along with the ways that the elements can becombined. A Schema is always a separate file with an extension of .xsd; a DTD is often a separate file withan extension of .dtd, but simple DTDs can be included in the XML document itself as part of the DOCTYPEdeclaration.

XMetaL | Working with XML and SGML | 29

DTDs, Schemas, and rules files

Although XML files can exist as well-formed stand-alone documents, most XML documents that you edit inXMetaL Author are associated with either a document type definition (DTD) or an XML Schema. Every SGMLfile that you edit in XMetaL Author must be associated with a DTD or rules file.

DTDs

A DTD is a file that describes document structure by means of declarations written in a formal notation definedin the SGML and XML standards. DTDs define the names of elements and describe the hierarchy of elements.

Schemas

XMetaL Author supports XML Schemas. Schemas provide restrictions and allow you to edit structured docu-ments without having to rely on a separate DTD. Schemas also expedite the exchange of information withcommon sets of rules, so that information is more quickly and easily passed between systems.

Limitations

There are some limitations to using Schemas with XMetaL Author:

• Identity-constraint definitions are ignored.

• The <redefine> tag is not supported.

• The instance attributes xsi:nil and xsi:type are ignored, and cannot be edited in Normal or Tags Onview.

• Checking an XML Schema (.xsd file) for errors is limited in XMetaL Author. It is recommended that you usethird-party tools, such as the ones available from the W3C Website, www.w3c.org.

Wildcards are not fully supported in XMetaL:

• xsd:anyAttribute is not supported

• the xsd:any processContents=skip and the xsd:any processContents=lax process contents controlsare not supported

• xsd:any processContents=strict is supported, but the used elements must be imported using<xsd:import>.

Example

<Schema targetNamespace="http://www.testing.com/Import" xmlns="http://www.w3.org/2001/XMLSchema" xmlns:a="http://www.testing.com/Import" elementFormDefault="qualified">

<import namespace="http://www.w3.org/1999/xhtml" SchemaLocation="xhtml1-transitional.xsd"/>

<element name="A"> <complexType> <sequence> <element name="B" type="string"/> <any namespace="http://www.w3.org/1999/xhtml" minOccurs="0" maxOccurs="unbounded"/> </sequence>

30 | XMetaL | Working with XML and SGML

</complexType> </element>

</Schema>

Rules files

XMetaL can use DTDs and Schemas in two formats: in their native text format, or as an XMetaL rules file. Arules file is a DTD or Schema that has been compiled into a binary format. Rules files for XML files have an.rlx file extension, rules files for SGML files have an .rls extension, and rules files for Schemas have an .rldfile extension.

Note: Typically, any DTD, rules file, or Schema that you need to use when working with XMetaL Authorwill be provided for you by the person in your organization responsible for customizing XMetaL Author.

Valid and well-formed markup

XML documents are said to be well-formed when they are structurally correct according to the XML standard.A well-formed XML document is considered valid if it conforms to a specified DTD or Schema. XML documentscan be well-formed without being valid; however, all valid XML documents are also well-formed by definition.

An XML document is well-formed if it is structurally correct according to the XML standard. There are severalaspects to well-formedness:

• The document must have only one top-level element that contains all the others.

• All elements must be properly nested (if an element’s start tag occurs inside an element, then its end tagmust occur inside the same element, and vice-versa).

• An attribute name cannot occur twice in the same tag.

• All characters must be in the character set defined by the XML standard.

• Entities may not be defined recursively.

XMetaL Author always creates markup (elements and attributes) that is well-formed.You can use XMetaLAuthor to edit well-formed documents without a DTD.

Because SGML documents must be linked with a DTD, it is not enough for them to be structurally correct(well-formed). They must also conform to their DTD. It is not possible to create or edit an SGML documentwithout an associated DTD.

When you are working with a document linked to a DTD or a Schema, XMetaL Author ensures that you donot create invalid markup. It does this in two ways:

• Validation, which you can run at any time to check that that the markup is correct and complete.

• Automatic rules checking, which is turned on by default when you are editing, and ensures that you do notbreak the required structure as you edit your document. As well, when you open a document or switch fromPlain Text view to Tags On or Normal view, XMetaL Author performs certain checks on the markup. Ruleschecking is less stringent than validation in that it checks that no errors have been made, but does notcheck that the markup is complete. For example, rules checking does not check required elements, unde-clared entities, or missing ID values.


Note: Rules checking and validation do not apply to well-formed XML documents that are edited withouta DTD.

XMetaL Author prevents markup errors in a number of ways:

• Commands are unavailable if using them would cause errors. For example, commands on the Insert menuare unavailable whenever it would be invalid to insert the related object.

• The Element List lists only those elements that can correctly be inserted in the current location.

• In some cases, XMetaL Author does not complete the command. For example, if you choose an elementfrom the Change List that cannot be correctly inserted at the current location, the element is not inserted.

• In other cases, you are given an opportunity to cancel a command that would create invalid markup. Forexample, if a Paste operation would leave the document incorrectly tagged, a warning pops up asking ifyou want to cancel the operation.

Validating the markup

You can validate an entire document, or you can select a selection of your document to validate.

Validation finds and reports any markup errors not caught by rules checking. In particular, it checks that thefollowing conditions have been met:

• All elements, attributes, and entities used in the document have been declared.

• All sub-elements of an element match that element’s content model.

• All required elements are present.

• All required attributes are present.

• All attributes are in the correct form.

• All ID attribute values are unique, and each IDREF attribute value matches an ID attribute value.

Once you have validated your document or selection, one of the following appears:

• A message confirming that your document is valid.

• A Validation Log containing a list of one or more error messages. To go to the location of an error, double-click the error message, or single-click the error message and click Go To.

Validate a document

1. Click Tools ➤ Validate Document.

Working without rules checking

In Normal and Tags On views, rules checking occurs automatically. However, in Plain Text view, rules checkingdoes not apply since markup is invalid most of the time when you are entering it by hand.

The current rules checking state is indicated in the lower right of the status bar. When rules checking is on,XMetaL Author ensures that the document being edited is correctly marked up; changes that would causeinvalid markup are not allowed.

If you are rearranging the content of your document, you may prefer to work with rules checking off (that is,in Plain Text view) while you cut and paste portions of the content and fix any invalid markup, and then turnrules checking back on by switching to Normal or Tags On view.

Note: Working in Plain Text view is recommended for advanced users only.


DOCTYPE declarations

An XML or SGML document should start with a Document Type Declaration (DOCTYPE). The DOCTYPEdeclaration associates the document with a DTD or rules file by means of an external identifier. Here is anexample of a DOCTYPE declaration:

<!DOCTYPE BOOK PUBLIC "-//Justsystems//Book v1.0//EN" "book.dtd">

The document type name follows the DOCTYPE keyword. By default, this is the top-level element in the DTDor rules file. However, as you are editing a document, XMetaL Author changes this to the current top-levelelement in the document.

External identifiers

An external identifier consists of the keyword SYSTEM or PUBLIC, followed by a system identifier or a publicidentifier followed by a system identifer. If the external identifier starts with SYSTEM, it has only a systemidentifier; if it starts with PUBLIC, it has a public identifier followed by a system identifier.The system identifiercan be a filename or URL.

Each identifier consists of a string of characters inside double quotes. The system identifier is generally thefilename of the DTD or rules file. The public identifier is an arbitrary identifier that is usually agreed upon bythe various organizations that use the DTD. Some DTDs that are used by a large number of organizationshave a standard public identifier.

Here are two DOCTYPEs, one with a PUBLIC keyword and one with a SYSTEM keyword, that could be usedto refer to the same DTD in either XML or SGML documents:

• <!DOCTYPE BOOK PUBLIC "-//Justsystems//Book v1.0//EN" "book.dtd">

The keyword PUBLIC indicates that the first identifier that follows it is the public identifier, and the secondidentifier that follows it is the system identifier. This DOCTYPE refers to a DTD that has the public identifier-//Justsystems//Book v1.0//EN and the system identifier book.dtd.

• <!DOCTYPE BOOK SYSTEM "book.dtd">

The keyword SYSTEM indicates that the identifier that follows it is the system identifier. If the externalidentifier starts with SYSTEM, there cannot be a public identifier. This DOCTYPE refers to a DTD that hasthe system identifier book.dtd.

The name after the word DOCTYPE is (usually) the name of the top-level element in the rules file; in theseexamples, that element is BOOK.

There is a third possibility for SGML documents only:


• <!DOCTYPE BOOK PUBLIC "-//Justsystems//Book v1.0//EN">

The keyword PUBLIC indicates that the identifier that follows it is the public identifier. In this example, thereis no system identifier. (DOCTYPE declarations in XML documents must include a system identifer.) ThisDOCTYPE refers to a DTD that has the public identifier -//Justsystems//Book v1.0//EN.

Internal subset

An internal subset in a DOCTYPE declaration is an optional part of the DOCTYPE enclosed in square brackets.It follows the document type name and the external identifier (if there is one).

<!DOCTYPE Article SYSTEM "journalist.dtd" [ <!ENTITY Title "Weasel populations in a forest in Poland"> ... ]>

The internal subset can contain markup declarations such as ELEMENT, ATTLIST, and ENTITY declarations.Declarations in the subset are read before declarations in the external DTD or rules file, and therefore theyoverride any external declarations of the same attribute or entity. Duplicate ELEMENT declarations are notallowed and result in an error message. ATTLIST declarations specifying different attributes of the sameelement are combined, but if the same attribute is specified in both places, the specification in the internalsubset takes precedence.

A DOCTYPE declaration can omit the external identifier, so that the document's DTD is internal (containedcompletely in the internal subset).

<?xml version="1.0" standalone="yes"?> <!DOCTYPE Article [ <!Element Article (Title, Sect1+)> <!Element Title (#pcdata)> <!Element Sect1 (Title,Para+)> <!Element Para (#pcdata)> <!Attlist Article Id ID #IMPLIED> ]> <Article> ... </Article>

The internal subset can refer to an external DTD using a parameter entity reference.

<?xml version="1.0"?> <!DOCTYPE Article [ <!Entity % journalist.dtd SYSTEM "journalist.dtd"> %journalist.dtd;]><Article> ... </Article>

When you create an entity with any of the entity-creation commands in the Tools menu, the entity declarationsare placed in the internal subset. However, note that if the internal subset contains any declarations otherthan ENTITY declarations, it is read-only in Tags On and Normal views, and the entity-creation commandsare unavailable.


Character encoding and Unicode support

In XMetaL Author, you can edit and save XML and SGML documents that use US-ASCII, ISO-8859-1 (Latin-1), Unicode(TM) UTF-8, or UTF-16 character encoding.

Note: The recommended encoding for XML documents is UTF-8.

When the appropriate fonts are installed on your computer and the customization for your Schema is configuredto use them, Unicode characters are displayed in the document pane. If a character appears as a box, thenthe font in use does not contain that character. The character will appear correctly when an appropriate fontis used.

You can enter Unicode characters using standard input devices (such as a keyboard), or IMEs (input methodeditors) on Windows 2000 NT 4.0 (with SP6a) and XP.You may also copy and paste characters from othertools such as the Character Map.

XMetaL Author determines file encoding by checking the following conditions, in the order specified, until anencoding is determined:

1. If the file contains a byte-order mark, XMetaL Author can determine whether it is UTF-8 or UTF-16.

2. If the file contains an XML declaration at the top of the file, then XMetaL Author then uses the rules inAppendix F of the XML specification (www.w3.org/TR/REC-xml#sec-guessing) to determine whether ornot the file is in UTF-16 format (it reads the characters <? in the XML declaration and infers the characterencoding based on the bytes used to represent these two characters).

3. If the file contains an XML declaration that explicitly specifies the encoding, then this encoding is used.For example:

<?xml version="1.0" encoding="UTF-16"?>

XMetaL Author accepts the following encoding strings for the four types of character encoding. Theseencoding strings are not case-sensitive.

Accepted Encoding StringsEncoding Type

ANSI_X3.4-1968US-ASCII

ANSI_X3.4-1986

ASCII

CP367

CSASCII

IBM367

ISO_646.IRV:1991

ISO646-US

ISO-IR-6

US

US-ASCII


Accepted Encoding StringsEncoding Type

CP819ISO-8859-1

CSISOLATIN1

IBM819

ISO-8859-1

ISO_8859-1

ISO_8859-1:1987

ISO-IR-100

LATIN1

L1

UTF-8UTF-8

UTF-16UTF-16

If the XML declaration in your document contains an encoding string not listed in the above table, an errormessage appears and the file is opened in Plain Text view. Plain Text view assumes ISO-8859-1 characterencoding.

4. If the encoding cannot be determined, then the default is used: UTF-8 for XML documents and ANSI(Latin-1) for SGML documents.

Opening and saving documents with Unicode encoding

XML files whose markup (element and attribute names, attribute values, etc.) uses the Latin-1 (ISO 8859-1)character set, and are encoded in the Unicode UTF-8 or UTF-16 encoding can be saved in the same format(“round-tripping”). File content can include any Unicode character. The character/entity conversion table(charentmap.xml), is used for mapping entity references to actual characters.

Rules for opening XML documents with Unicode encoding

When you open an XML file with Unicode encoding, the characters are interpreted according to the followingrules, which are applied in the order shown:

1. The XML entity references for the characters <, >, and & are converted from entity references to characters.

2. Other entity references are converted to characters if they are mapped to characters in the character/entitytable (charentmap.xml), and if your operating system and version of XMetaL Author is capable of displayingthe character.

Rules for saving XML documents with Unicode encoding

When you save an XML file with Unicode encoding, the characters are saved according to the following rules,which are applied in the order shown:

1. The characters <, >, and & are converted to their respective entity references.

2. If the document encoding allows for it, characters are saved as actual characters.


3. If the character/entity table (charentmap.xml) has an entity reference corresponding to the character, thecharacter is saved as an entity reference.

4. If none of the above rules apply, the character is saved as a character reference.

For Unicode UTF-8 or UTF-16 encoding, characters are always saved as they are. For documents with ASCIIand Latin-1 encodings, non-ASCII or non-Latin-1 characters are saved as entity references if they are in thecharacter/entity table, and as character references if they are not.

Rules for opening SGML documents with Unicode encoding

When you open an SGML file with Unicode encoding, entity references are converted to actual characters ifthey are mapped to characters in the character/entity table (charentmap.xml), and if your operating systemand version of XMetaL Author is capable of displaying the character.

Rules for saving SGML documents with Unicode encoding

When you save an SGML file with Unicode encoding, the characters are saved according to the followingrules, which are applied in the order shown:

1. If the character/entity table (charentmap.xml) has an entity reference corresponding to the character, thecharacter is saved as an entity reference.

2. If the document encoding allows for it, characters are saved as actual characters.

3. If neither rule 1 nor 2 applies, the character is saved as a character reference.

Inserting commentsYou can add text comments to your document using the Comment command. If you are working in a DITAdocument, you can also add a <draft-comment> element.

Text comments (that you enter using the Comment command) are not displayed by browsers, but can beviewed in XMetaL Author if the Show comments option is active.

Comments that you enter using the <draft-comment> element can contain text and other elements.You cancontrol the display of this type of comment through the Advanced tab in the Configure Output Optionsdialog.

Insert a text comment

Switch to Tags On view for this procedure.

1. Position the insertion point in your document where you want to insert a comment.


• If you are working in a DITA document, click Insert ➤ Advanced ➤ Comment• Click Insert ➤ Comment

3. Type your comment inside the tags.


CDATA sections

If the text of your XML or SGML document contains markup characters (<, >, or &), and you do not want tointerpret these characters as markup, you can surround them with CDATA sections. Doing so enables youto use samples of XML or SGML markup in your documents.

If you enter markup characters in plain text in an XML file, XMetaL Author converts them to the equivalentbuilt-in entity (defined in the XML specification). If you want to prevent the character from being interpreted,you must insert it in a CDATA section.

CDATA sections cannot be nested.

Note: You should not enter the character sequence ]]> in a CDATA section. This terminates the sectionand probably causes a markup error.

Insert a CDATA section


• In Tags On view, click in the document where you want to insert a CDATA section.• In Tags On view, select the markup character(s) in your document that you want to mark as a CDATA

section.

2. Click Insert ➤ Advanced ➤ CDATA Section.

Marked sections

In SGML documents, you can use marked sections to isolate content and indicate how it should be processed.Although there are several different types of marked sections available to SGML documents, including CDATAsections, XML documents can contain only CDATA sections.

The most common use of marked sections is to isolate parts of the document so that they are either read orignored by the application that is reading the document. For example, a workbook could be printed in twoversions: one for teachers that includes both questions and answers, and another for students that has onlythe questions. A single SGML document could be used for both versions. In this document, the answers arein marked sections that can be ignored when the student version is processed.

Marked sections can also be used to mark a section of the document as temporary, or to include fragmentsof “raw SGML” in your document and not have them interpreted as markup.

Like elements, marked sections start and end with tag icons, . The result parameters ofthe marked section are displayed inside the start-tag. More.

Marked section parameters

The five parameters that you can choose for a marked section have the following meanings:


The contents of the marked section should be read by the application. This parameter is thedefault, and is considered to be selected unless you select the IGNORE parameter.

INCLUDE

The contents of the marked section should be ignored by the application. The applicationshould behave as if the contents of the marked section were not present in the document.Selecting (checking) the Ignore Contents check box chooses IGNORE.

IGNORE

Temporary: you can choose this parameter if the marked section contains material that islikely to be removed later, for example, a formatting instruction inserted for a particular print

TEMP

run.This parameter makes it easier to locate and remove such sections.TEMP is just a labeland does not, by itself, cause any special processing. Selecting (checking) the Mark asTemporary check box selects TEMP.

The marked section can contain only character data (CDATA). This means that the markedsection cannot contain any elements or entities: XMetaL Author does not allow you to use

CDATA

menu commands to enter an element or an entity reference. If the marked section containsa tag or entity that is entered as ordinary text, XMetaL Author or any another applicationtreats it as text rather than markup. Choosing Text only (CDATA) from the Special Contentslist selects CDATA.

The marked section can contain only replaceable character data (RCDATA). Different fromCDATA, this means that the marked section cannot contain any elements, but can contain

RCDATA

entities. XMetaL Author does not allow you to enter an element using Element. If the markedsection contains a tag that is entered as ordinary text, XMetaL Author or any another appli-cation treats it as text rather than markup. Choosing Text and Entities (RCDATA) from theSpecial Contents list selects RCDATA.

Result parameters

You can choose marked section parameters in any combination. Some of them override others, so XMetaLAuthor evaluates all parameters to arrive at the result. In Tags On view, these appear at the bottom of theMarked Section dialog box with the label RESULT PARAMETERS, and inside the marked section icon. Theresult parameters determine how the marked section is processed.

XMetaL Author uses the following rules in calculating the result parameters:

• TEMP is not overridden by any other parameter.

• IGNORE overrides INCLUDE, CDATA, and RCDATA.

• CDATA overrides RCDATA.

• INCLUDE is the default parameter for all marked sections; if IGNORE has not been chosen, then INCLUDEis one of the result parameters. However, since it is the default, it is not displayed in the dialog box unlessit is the only parameter.

Because of these rules, there are actually only eight possible sets of result parameters:

• IGNORE

• IGNORE TEMP


• INCLUDE

• TEMP

• CDATA

• RCDATA

• CDATA TEMP

• RCDATA TEMP

If the IGNORE parameter is not specified, the INCLUDE parameter is implied. It does not have to be stated.

Restrictions on marked section parameters

If a selection contains markup icons (start tags, end tags, and entity icons), some marked section parametersmay not be permitted for that selection:

• A selection that contains start and end tag icons cannot be surrounded by a marked section that has theresult parameters CDATA or RCDATA.

• A selection that contains an entity icon cannot be surrounded by a marked section that has the resultparameter CDATA.

• A selection that contains a required element (an element that must be in place for the document to be valid)cannot be contained within a marked section with the IGNORE parameter.

XMetaL Author does not prevent you from entering tags or an entity in a marked section as “raw text”. If youhave typed in a start-tag, for example, you are allowed surround it with a marked section containing one ofthe special content (CDATA or RCDATA) types.

Insert a marked section

1. In Tags On view, insert a CDATA section.

2. Switch to Plain Text view.

Your CDATA section will look similar to this:

<![CDATA[example text]]>

3. Replace the CDATA parameter with the marked section parameter(s) you want to use.

For example

<![IGNORE TEMP[example text]]>

4. Switch to Tags On view.

You should see the tags of your marked section parameter. The example in the previous step would looklike this:


Entities and special characters

You can use an entity to include text or other content in an XML or SGML document by substituting a shortreference to it, called an entity reference. An entity reference can stand for any of the following:

• Specific text. This type of entity is called a text entity.This is a powerful way to insert paragraphs or phrasesof “boilerplate text” (text that you use frequently).You type the text only once, when you are creating thetext entity, give it a name to use as the entity reference, and then insert the entity reference in the documentwherever the text should appear. Text entities are also useful for words, names, or phrases that are usedthroughout a document, but that may change, such as product names or version numbers. In these cases,you make the change only once, to the text entity itself, rather than having to find and change the textthroughout the document.

• A multimedia file. This can be an image or sound file. This type of entity is called a graphic entity.

• An XML or SGML file. This type of entity is called an external entity.

All of these entities are collectively referred to as general entities.

General entities can be defined in the DTD or rules file, or in the document itself. Entities created in the doc-ument are stored in the internal subset of the DOCTYPE declaration.

XML also uses another kind of entity specifically for certain typographical characters, such as symbols andaccented letters, not normally found on US keyboards. These entities are called character references. Forexample, the character reference … stands for the ellipsis character (...). Unlike general entities,character reference entities do not have to be explicitly defined because they are included in the XML speci-fication.

Note: You can also use named character entities, for example, …, but these must be defined inyour DTD.

Entity naming conventions

Follow these rules for entity names:

• The first character of the name must be a letter.

• In SGML files, the remaining characters must be letters, digits, or the period (.) or hyphen (-).

In XML files, The underscore (_) and colon (:) are also allowed, but the colon should be avoided unlessyou are indicating a namespace.

• In SGML files, names cannot be longer than 128 characters. There is no such limitation for entity namesin XML files.

• A document cannot have more than one entity with the same name, even if they are different types ofentities. However, entity names are case-sensitive. For example, ProdName and Prodname are consideredto be different names.

If an entity name has already been used in the DTD or rules file, you can define an entity with the same namein the document, but XMetaL Author displays a warning to make sure you are aware of the other entity. Theentity in the document overrides the one in the rules file.


Creating and editing text entities

The Text Entities command enables you to create new text entities, and delete and change existing ones.

A text entity has the following parts:

• The name of the entity

• The content of the entity

• The content type of the entity (optional)

Text entities are usually displayed as rectangular icons ( , for example) in Tags On view, and as theentity’s replacement text (the content) in Normal view.

The default content type parameter for text entities is CDATA. If you are working with an SGML documentand you want your text entity to contain some other type of text, you must switch to Plain Text view, find theentity declaration within the DOCTYPE declaration at the top of the document, and replace the parameterCDATA with the parameter corresponding to the type of text entity you want.

Text entity content types

For SGML documents, there are four possible content types:

• Character Data (CDATA). This parameter is used when the content of the text entity includes one or moreof the characters used in SGML markup, such as “&” or “<”. For example, an entity whose content is thephrase “R&D” should be defined as character data, otherwise “&D” will be interpreted as a reference to anentity “D”. The entity declaration for a CDATA text entity would look like this example:

<!ENTITY entityname CDATA "entity text">

This is the default parameter for XMetaL Author text entities.

• Specific Character Data (SDATA). This parameter is used the contents of the text entity include system-specific data such as an escape sequence that represents a specific character to a particular text formatter.Here is a sample SDATA text entity declaration:

<!ENTITY entityname SDATA "entity text">

• Processing Instruction (PI). Use this parameter when the text entity contains a processor-specific formattinginstruction. An example of this would be a troff request. Here is a sample PI text entity declaration:

<!ENTITY entityname PI "entity text">

• (blank). If the content of the text entity does not fall into one of the above three categories, you do not needinclude a text content parameter, as in this example:

<!ENTITY entityname "entity text">

Creating and editing graphic entities

Graphic entities are normally used to refer to external multimedia files such as image, video, or sound files.If your DTD contains one or more NOTATION declarations, you can add, change, and delete graphic entitiesin your document.


Graphic entities are normally displayed as rectangular icons (for example, ) in Tags On and Normalviews.

Graphic entities have the following content types:

• Notation. The graphic entity consists of non-SGML characters. Almost all graphic entities will be of thistype.

• Char. Data. The data in the graphic entity is not system-specific.

• Specific Char. Data. The graphic entity contains characters understood only by a local formatting system.

Creating and editing external entities

External entities are used to represent external XML and SGML files.You can create new file entities andremove and change existing ones.

When you insert an external entity into your document, it is displayed as a rectangular icon (for example,

) in Tags On and Normal views. If you double-click the entity icon, XMetaL Author attempts to openthe file that the entity represents.

The contents of the file referred to in an external entity are parsed just as if they occurred in-place in thecurrent document instead of in another file.

Creating and editing parameter entities in SGML documents

Parameter entities are similar to text entities, but instead of referring to text, they refer to one or more markedsection parameters.

Create an entity


• Click Tools ➤ Text Entities• Click Tools ➤ Graphic Entities• Click Tools ➤ External Entities• (SGML only) Click Tools ➤ Parameter Entities

2. Type a name for the entity.


• For text entities, type the text content.This is the text that will appear in your document when you insertthe entity.

• For graphic or external entities, click Choose and select a file.• For parameter entities, set the parameters for the entity.

4. (SGML only) Do one of the following:

• For text entities, select an option from the Entry Contains list.• For graphic entities, select an option from the Content Type list.


• For graphics entities, select the type of graphics file represented by the entity. This is usually indicatedby the filename extension, such as .bmp or .gif. Graphic types correspond to NOTATION declarationsin the DTD.


• (SGML only) For external entities, check the Subdocument option if you want to define the externalentity as a subdocument.Your DTD must support this.

6. Click New.

Change an entity



2. Click the entity whose contents you want to modify.

3. Make the desired changes.

4. Click Change.

Delete an entity



2. Click the entity you want to delete.

3. Click Delete.

Inserting general entity references

After you have defined a text, graphic, or external general entity, you can include it in your XML or SGMLdocument by inserting an entity reference. In XMetaL Author, you can insert an entity reference in your doc-ument by selecting the name you assigned to the entity from the Insert Entity dialog box.

Available entities are arranged in entity sets. Entities defined (or already used) in the document are in theDocument entity set.The other entity sets contain entities declared in the DTD (Rules File) entity set and anyexternal files that are referenced in the DTD.

Insert an entity referenceWhen an entity has been inserted, it is added to the Document entity set if it was not already there.

1. In your document, click where you want to insert an entity reference.

2. Click Insert ➤ Entity Reference.

3. From the Entity Set list, select the entity set that contains the entity you want to insert.

4. Select the entity you want to insert in your document.

5. Click Insert.


Typing special characters and symbols

The Special Characters toolbar and the Symbols toolbar allow for easy entry of special characters (uppercaseand lowercase letters with accents used in European languages other than English) and symbols (currency,mathematical, punctuation, and publishing symbols) that do not have a corresponding key on US keyboards.

By default, XMetaL Author converts these characters to the equivalent entity references, if the entities havebeen declared. For example, the “less-than” symbol (<) is converted to the entity reference <.The charactersare displayed as the characters themselves in Tags On and Normal views. In Plain Text view, they appearas entity references.

Note: If your document’s encoding supports the character, the character, not the character entity, issaved.

Euro symbol

The character entity reference for the Euro symbol is €.This symbol is also available from the Symbolstoolbar.

Enter a special character or symbol


• Click Insert ➤ Special Characters• Click Insert ➤ Symbols

2. Place the cursor at the point in your document where you want to insert the special character or symbol.

3. On the toolbar, click the character or symbol.

Converting between entities and characters

By default, if a file on disk contains an entity or character reference that represents a character in the ISOLatin 1 (ISO8859-1) or ISO Numeric character set, it is converted to the equivalent character when you openthe file (or switch from Plain Text view to Tags On or Normal).

When you save a document or switch to Plain Text view, any special characters (such as those in the ISOLatin 1 or ISO Numeric character sets) are converted to the equivalent entity or character reference.


Working with elements

Elements are usually named according to their function in the document. For example, <section> describesa section, <title> describes a title. An element can contain text, attributes, or other elements.The document’sDTD defines the list of elements available in your document and the sequence in which they must appear.

The current element refers to the element inside of which the insertion point is positioned. In Normal andTags On views, the context bar to the left of the horizontal scrollbar displays the current element precededby its ancestors. Various operations, such as changing the element type and editing attributes, apply to thecurrent element.

Note:

If you select an entire element, the current element is not the selected element. In this case, the parentof the selected element is the current element.

Special element types

• Empty elements. These elements cannot have any text content. In XML, an empty element appears as

<TAGNAME/> in Plain Text view, and in Tags On view. An SGML element appears

as <TAGNAME> in Plain Text view, and in Tags On view. Empty elements are also

designated by the icon in Normal and Tags On views. Empty elements are often used to referenceimages.

• Read-only elements. The content or attributes of these elements cannot be edited.

Inserting elements

In Normal and Tags On views, you can think of elements as:

• Structural elements

• Formatting styles

Since documents are formatted differently by each rendering agent (for example, a browser), you may preferto think of elements as standing for parts of the document’s structure (for example, heading, paragraph, listitem) without thinking explicitly about how they are formatted. On the other hand, if you are accustomed toworking with desktop publishing or word processing applications, you may want to think of the elements asstyles.

XMetaL Author supports both approaches to markup. Working in Normal view is similar to applying wordprocessing styles; Tags On view is oriented toward thinking of elements as structural objects.

In Normal and Tags On views, the list of available elements is displayed in the Element List. The Used tabcontains up to 10 of the most frequently used elements in this editing session that are valid in this context.All of the elements that are valid in this context are available in the All tab.

Note: In Plain Text view, the All tab contains all of the elements in the DTD, not just the valid ones.

The next required element in the current context is displayed in bold.

46 | XMetaL | Working with elements

In some circumstances, when you insert an element, XMetaL Author automatically inserts prompt text andchild elements that are necessary to conform to the DTD.You can replace prompt text with your own content.If you type at a location where text is not allowed, XMetaL Author surrounds the text with the first valid para-graph element if one or more have been configured for the current DTD.

Insert an element

1. Place the insertion point at the location in the document where you want to insert an element.

You may find working in Tags On view easier for this.


• In the Element List, select an element and click Apply• Click Insert ➤ Element using Element List• Click Insert and select an element type

If the document contains a selection, the new element surrounds it.

Change an element

1. Place the insertion point inside the element you want to change.


• Click Edit ➤ Change Element.• In the Element List pane, click the Change option.

3. In the Element List pane, click the All tab, if necessary, then click the desired element.

4. Click Apply.

Splitting elements

Splitting an element creates two elements, sometimes of the same type as the current element, and sometimesnot. If there is content in the element, the first element contains all the content before the insertion point andthe second element contains the remaining content. If the insertion point is just after the start tag, or justbefore the end tag, a new, empty element is created.

Split an element

1. Position the insertion point where you want to split the element.


• Click Edit ➤ Split Element.• Press Enter.

XMetaL | Working with elements | 47

Join two adjacent elements


• In Tags On view, place the insertion point just after the start tag for the second element and pressBackspace

• In Tags On view, place the insertion point just before the closing tag for the first element and pressDelete

• Click anywhere in the second element, and then click Edit ➤ Join Element to Preceding

If the elements have attributes, then the attributes of the first element are adopted for the new, combinedelement.

Remove elements


• Click just after the start-tag for the element, and press Backspace• Click anywhere directly in the element (that is, not in a sub-element), and then click Edit ➤ Remove

Tags• Select the entire element, including open and close tags, and press Delete.

Remove tagsYou can remove the tags surrounding an element and place its content directly inside the parent element.


• Place the insertion point inside the element and click Edit ➤ Remove Tags• Place the insertion point inside the element and press Ctrl+Shift+D

48 | XMetaL | Working with elements

Working with attributes

Attributes consist of name/value pairs and are used to provide more information about an element. The doc-ument’s DTD specifies which elements have attributes and the types of values the attributes can have.

In XML, attributes are separated from the element name by a space, and attribute values are enclosed inquotation marks. For example, the element <section audience="advanced"> is designated as containinginformation for an advanced audience. Attribute values are not part of the element’s text content.

You can edit attributes for any element using the Attribute Inspector.You can edit attributes by placing theinsertion point anywhere inside an element.

Tip: You may find that working in Tags On view helps you position the insertion point.

The Attribute Inspector displays the attributes of the current element.

In Tags On view, attribute values appear in tag tips when you rest the mouse cursor on a tag in the documentpane. In Normal view, tag tips display the attributes of images.

Special characters in attribute values

The following characters must be escaped.

<<

>>

""

''

&&

Special attribute types

• Required attributes. A required attribute is one that must be given a value, or else the file is not valid. Thenames of required attributes are displayed in bold in the Attribute Inspector.When the document is validated,XMetaL Author checks that all required attributes are present.

• IDs and IDREFs. A DTD may declare certain attributes as IDs or IDREFs.

IDs are unique identifiers. The value of an ID attribute must not be used for any other ID attribute in thedocument. When the document is validated, XMetaL Author checks that the identifier is unique, and that itcontains the correct kind of characters (by default, an identifier must start with a letter, and contain onlyletters, numbers, hyphens, and periods).

IDREFs refer to IDs. The value of an IDREF attribute must be the value of an ID attribute somewhere in thedocument. When the document is validated, XMetaL Author checks that the corresponding ID attributeexists in the document. Unlike ID attributes, IDREF attributes do not have to be unique: more than oneIDREF can refer to the same ID.

It is also possible to declare an attribute as an IDREFS attribute. This kind of attribute is similar to an IDREF,but its value can be a list of IDs, separated by spaces.

XMetaL | Working with attributes | 49

• Name token groups. A DTD can restrict the possible values of an attribute to a finite list, called a nametoken group. For example, an attribute called COLOR may have the possible values red, green, and blue.When the document is validated, XMetaL Author checks that the attribute value is from the specified group.

• FIXED attributes. Some attributes are declared with a fixed value in the DTD. These attributes are calledFIXED attributes and are displayed in grey text in the Attribute Inspector. Their values cannot be modified.

Edit an attributeYou can edit attributes for the current element or any of its ancestors.

1. Place the insertion point anywhere inside an element.

2. Click View ➤ Attribute Inspector.

3. In the list at the top of the Attribute Inspector, click the name of the element whose attributes you wantto edit.

This list contains the current element and all of the elements that enclose it (Normal and Tags On viewsonly).You can use this list to edit attributes of an ancestor of the current element.

4. Click the attribute you want to edit.


• If the editing field has a drop-down arrow button, click the button and choose a value from the list• If the editing field is a text box, type the appropriate value

6. Press Enter.

50 | XMetaL | Working with attributes

Working with files

Creating a new document

Unlike word-processors, when you create a new file in XMetaL, you need to choose a DTD, Schema, or rulesfile.You can do this either by creating a new document from a template (which is based on an DTD, Schema,or rules file), or by creating a blank XML or SGML document and specifying the file for the new document.

Create a document from a template

1. Click File ➤ New.

2. Click the desired tab (do not use the General tab), and choose a template.

Create a blank documentWhen you create a blank SGML or XML document, a dialog appears asking you to choose a DTD, Schema,or rules file.


2. Click the General tab.

3. Choose one of the following:

• Blank SGML Document• Blank XML Document

4. Choose the DTD, Schema, or rules file for the document you want to create.

Opening documents

You can open XML or SGML documents through the Open command.You can also open files by draggingand dropping them from another application (such as Windows Explorer) onto the background of the XMetaLAuthor work area.

XMetaL Author determines whether to edit the file as an XML or SGML file by testing the following conditionsin the order given, and stopping as soon as one of the conditions is true:

• If the file starts with an XML declaration, it is edited as an XML file.

• If the file does not start with an XML declaration and if the filename has the .sgm or .sgml file extension, itis edited as an SGML file.

If none of the conditions above is true, the file is edited as an XML file. In this case, XMetaL adds an XMLdeclaration to the document.

XMetaL | Working with files | 51

Opening files on a Webdav folder

You can open remote files in XMetaL Author the same way that you open a local file. Files that are alreadyopen and in use by another user cannot be opened for editing. In this case, XMetaL Author alerts you thatthe file is in use and prompts you either to open the file as read-only, or to cancel the opening operation.

You must have network permission to open the remote file. Contact your system administrator to set up ormaintain these privileges.

Note: Internet Information Server (IIS) Version 5.0 must be installed, and the folder containing the targetfiles must be Web Share enabled.

Open a file

1. Click File ➤ Open.

2. Select a file.

3. If necessary, choose an option in the Rules Not Specified dialog.

Open an XML file displayed in a browser

1. Open an XML file in a browser.

2. In the Address bar, click the file icon and drag it onto the background of the XMetaL Author work area.

Note: If the document pane is maximized, drag and drop files onto the square area where thehorizontal and vertical scrollbars meet.

What to do if the DTD, Schema, or rules file cannot be found

Sometimes XMetaL Author may not be able to locate a DTD, Schema, or rules file for the file you are opening.This could happen for any of the following reasons:

• The file has no DOCTYPE declaration, which associates a DTD or rules file with the XML or SGML file,using external identifiers.

• The catalog and/or external identifier map files do not contain entries that map the external identifier in theDOCTYPE with a rules file or DTD.

• The DTD or rules file is not at the expected location:

• An (incorrect) absolute location may have been specified in the catalog or external identifier map file.

• If a relative location was specified, it should be relative to the location of the XML or SGML file.

If XMetaL Author cannot find the rules file or DTD, and the document does not conform to a W3C schema,a dialog box appears offering you the following choices:

• Browse for a DTD. Enable this option to open a dialog box from which you can select a DTD, schema, orrules file. If you choose the correct rules file, DTD, or schema, the document opens and you can edit it inthe normal way.

• Edit as a partial document. (Not applicable to XML files based on schemas.) Enable this option to openthe document as a well-formed document in your default editing view (Normal or Tags On).You can editelements and attributes, but no validation takes place.

52 | XMetaL | Working with files

• Edit the file in plain text view. Enable this option to open the document in Plain Text view, so that no ruleschecking occurs.

For both of the last two options, you can enable the Choose Auxiliary DTD option.When this option is enabled,the elements and attributes from the auxiliary DTD you select are added to the document you are editing,but XMetaL Author does not use the DTD to validate the document. This means that the document does notneed to conform to the structure of the DTD, and you can add elements and attributes as necessary.

Note: In most cases, you should contact your technical support department or the creator of your XMetaLcustomization for assistance.

Opening files in WebDAV-enabled folders

When you open a document located in a WebDAV folder, the document is automatically locked. This meansthat only you can save changes to the document as long as you have it open. Locked files can be read(opened) but not saved by others. Auxiliary files such as the DTD are left unlocked.

When you finish editing the document and close it again, the file is unlocked, and is therefore available forediting by others.

If you try to open a document from XMetaL Author that is in a WebDAV-enabled folder and has already beenopened, a message appears telling you that the file is already open and being edited.

Customization files (for example, .mcr or .tbr files.), including XAC files, can be downloaded from a WebDAVserver following the normal search rules. Catalogs are not downloaded from a WebDAV server; only yourlocal system is searched according to the normal search behavior for catalogs.

In order for WebDAV functionality to occur, the folder must already be set up (through your operating system)to be a WebDAV folder. Contact your System Administrator for information on setting up WebDAV folders.

File caching

Files retrieved through WebDAV are stored locally in the Windows temporary folder (usually C:\Documentsand Settings\<username>\Local Settings\Temp).When you open a file from a WebDAV server, the URLto this local path is mapped, and the cached file is used. If the file in the cache does not exist, the file is firstretrieved from the WebDAV folder and placed there. After the document is closed, all the cached items usedby the document are removed.

Opening external file entities

The XMetaL Author document pane displays a reference to an external entity as a rectangular icon containingthe entity name. If you double-click the icon, XMetaL Author attempts to open the XML or SGML file that theentity represents.

Saving documents

You can save a document using its current name and folder location, save a document under a differentname or in a different location, or save all open documents to their current name and location.

You can also set certain save options such as automatic saving and backup creation.


XMetaL Author automatically validates the document before saving it. If validation errors are found, a ValidationLog dialog box appears listing the errors. Click an error to take you to the relevant position in the document.Additionally, a confirmation dialog box appears telling you the document is not valid and giving you the optionof saving the invalid document or cancelling the save operation.

The Save All command saves all of the documents that you have open in XMetaL Author. If you are creatingnew documents, the Save As dialog box prompts you to name each file sequentially. If the documents areexisting documents, they are all saved without any prompting.

Save a document

1. Click File ➤ Save.


• Click Save in the confirmation dialog box that appears• Click Cancel, fix the validation errors listed, and try saving the document again

Save a document to a different filename or location

1. Click File ➤ Save As.

2. Navigate to the folder in which you want to save the document.

3. Type a name for the document in the File name box.

4. Click Save.


• Click Save in the confirmation dialog box that appears• Click Cancel, fix the validation errors listed, and try saving the document again

Note: Do not try to save an XML file as SGML or an SGML file as XML by typing a different fileextension in the File name box. XMetal Author does not support saving XML as SGML or vice-versa.

Save all open documents

1. Click File ➤ Save All.


• Click Save in the confirmation dialog boxes that appear• Click Cancel, fix the validation errors listed, and try saving the documents again

Closing documents

You can close an open document and choose whether or not to save any changes made to the document.You can also close all open documents.

Close a document

1. Click File ➤ Close.


If changes have been made to the document and not saved, a confirmation dialog box appears asking ifyou want to save the document.


• If necessary, click Yes to save your changes and close the document• Click No to close the document without saving your changes• Click Cancel

Close all open documents

1. Click File ➤ Close All.

If changes have been made to the documents and not saved, a confirmation dialog box appears for eachdocument with changes asking if you want to save the document.


• If necessary, for each changed document, click Yes to save your changes and close the document• Click No to close the document without saving your changes• Click Cancel

Moving between open documents

If you have more than one document open in XMetaL Author, you can move between the open documentsin a variety of ways.

Move between documents


• Click the appropriate file name on the Window menu• If you are in workbook mode, click the document’s tab• Press Alt+Right Arrow or Alt+Left Arrow• Click Next Document/Previous Document on the Standard toolbar

Editing well-formed XML documents

Normally, XML documents conform either to a Schema or a DTD or rules file, but you also have the optionof editing well-formed XML documents that are not based on a Schema or DTD.

As part of creating and editing a well-formed document that does not conform to an existing DTD or Schema,you must also create the document elements.You can define attributes for your elements as well.

Alternatively, you can specify a DTD, Schema, or rules file to supply a set of elements and attributes for thedocument. If you choose such a DTD or rules file, XMetaL Author adds a processing instruction to your doc-ument that points to it. Any elements and attributes specified in the DTD are available to the document, butbecause the document is not officially based on the DTD, no rules checking or validation of the documentoccurs. All attributes are of type CDATA, that is, they can contain text without restriction.


By default, if you are editing in well-formed mode, the Attribute Inspector and Element List display only elementsand attributes that are currently in the document.

Note:

• If you try to open a DTD-less XML document that is not well-formed (for example, there is a missing,misplaced, or badly-formed start- or end-tag), XMetaL Author attempts to fix the markup so that itbecomes well-formed. However, since there is no DTD to indicate the structure of the elements, theresults may not be what you want.

• SGML documents cannot be edited without a DTD or rules file.

Create a well-formed XML document


2. Click the Well-formed tab.

3. Click the Blank Well-Formed XML Document icon.

4. Click Open.

5. Add elements to your new document.

6. Add elements to your new document (see below). (You cannot enter content until you have created atleast one element.)

Documents created as well-formed contain the following declaration just after the XML declaration:

<?xm-well_formed path = ""?>

Define an element

1. In the Element List, double-click <Add new element> at the top of the element list.

2. Type a name for the element.

3. Type a short description for the element.

This description will appear at the bottom of the element list when the element is selected.

4. Choose an option:

• Element can be a container. Enable this option if you want the element to be able to contain text and/orother elements.

• Element is empty. Enable this option if you do not want the element to have any content.

Define an attributeAll new attributes created in well-formed documents can have plain text (CDATA) content.

1. Right-click anywhere in the Attribute Inspector, and click Add Attribute.

2. Type the desired attribute name.

3. Type a short description of the attribute.

This description will appear as the help string for this attribute, at the bottom of the Attribute Inspector.


Printing documents

Printing is available from all three document editing views: Normal, Tags On, and Plain Text. The documentprints as it appears in the current view, with tags icons in Tags On view, and as source code in Plain Textview. Color printing is not supported from these views.

You can also create headers and footers for your printed document.

Print a document

1. Click File ➤ Print.

2. Optional: Click Options and create headers and footers.

Print from a browser

1. Click View ➤ Page Preview.

2. Right-click in the browser pane and choose Print.


Selecting and editing text

You can work with text in XMetaL Author much the same way you would in a word processing application.There are, however, some differences that reflect the fact that you are working with a structured documentthat contains markup as well as text. This topic describes how to use XMetaL Author to work with the text inyour document.

Selecting text

You can select text in XMetaL Author just as you would in a word processing application.There are, however,some rules about selecting markup that limit how you can select text. These rules prevent you from creatingan invalid document by deleting or moving markup inappropriately. For example, each time you select a startor end tag when you select text, the corresponding tag (and all the text in between) is also selected.Therefore,you cannot make a selection that includes only a beginning element tag or an ending element tag. However,there are no restrictions on selecting text within an element.

The following three samples show possible text and markup selections in Tags On view.

Tip: Switch to Tags On view to make sure you are not trying to select text across markup boundaries.

Text selected within an element (Para) and not including any markup:

Selection of an entire element (Emphasis), including both markup and text:

Text selected within an element (Para), including an entire child element (Emphasis):

The type of selection shown in the next sample, however, is not possible.

58 | XMetaL | Selecting and editing text

Selection of an element start tag (Emphasis) but not the end tag:

Do this:To select this:

Double-click the word you want to select.A single word

Click Edit ➤ Select Element.A single element

Click anywhere in the first element to be selected and dragin the appropriate direction until all of the elements areselected.

Consecutive elements

With the insertion point anywhere in the document, pressCtrl+A.

The entire contents of a document

Editing selections

In XMetaL Author, you can cut, copy, and paste selected text and markup using menu commands, shortcutkeys, or by dragging and dropping. However, just as there are rules for selecting text and markup, there arealso rules about how and where text and markup can be deleted or inserted. Removing or pasting certainelements can cause invalid markup in some circumstances. Usually, you cannot delete a selection if it includesrequired elements. Similarly, XMetaL Author will not paste a selection that would cause the markup to becomeinvalid.

Copy and paste a selection

1. Select the part of the document that you want to copy.


• Click Edit ➤ Copy, click in the new location, and click Edit ➤ Paste• Release the mouse key, then while pressing the Ctrl key, click and drag the selection to the new location

Note: If your selection cannot be inserted at the cursor location without invalidating the document,and if rules checking is on, the selection is not inserted.

Move a selection

1. Select the part of the document that you want to move.


• Click Edit ➤ Cut, click in the new location, and click Edit ➤ Paste• Release the mouse key, then click and drag the selection to the new location

XMetaL | Selecting and editing text | 59

Note: If your selection contains markup that cannot be inserted without invalidating the document,or if your selection contains elements required at their current location, and if rules checking is on,the selection is not moved.

Delete a selection

1. Select the part of the document that you want to delete.

2. Click Edit ➤ Delete.

Note: If rules checking is on, XMetaL Author does not delete selections that contain required elements.

60 | XMetaL | Selecting and editing text

Finding and replacing text

In XMetaL Author, you can find and replace text, elements, and entities. Find and replace operations aresimilar to those in word processing applications, with the following differences:

• Text searches do not find a match if part of the text is found in a separate element. For example, if you aresearching for “World Wide Web” and the word “Web” is in an <EMPH> element, no match is found.

• In Tags On and Normal views, element replacements that would invalidate the markup do not occur if ruleschecking is on. If such a replacement occurs in a “ replace all” operation, it is skipped.

XMetaL Author offers the following search options:

• Match case. Enable this option to find only text that matches the text in the Find box exactly, matchingupper-case to upper-case and lower to lower.

• Match whole words only. Enable this option to match a sequence of one or more whole words only.

• Use Pattern Matching. Enable this option to search by patterns (the characters in the Find text box areinterpreted as patterns). If this option is disabled, any special search characters in the search or replacetext are treated as ordinary characters.

• Search backwards. Enable this option to search for the requested word from the current location towardsthe beginning of the document.

• Wrap. Enable this option to search from the current location to the bottom of the the document, and thencontinue searching from the top of the document (or searching to the top and starting again from the bottom,if Backwards Search is enabled).

• Ignore read-only on replace. Enable this option to ignore read-only elements when replacing text. If thisoption is disabled, an error message appears whenever XMetaL Author attempts to replace text within aread-only element.

Searching for text

You can search for text that occurs anywhere in your document, and replace it with different text or with atext entity.You can also restrict your search so that you find specific text only when it occurs within a specificelement.

Find and replace text

1. Click Edit ➤ Find and Replace.

2. In the Find box, type the text that you want to find.

3. In the Replace with box, type the replacement text (if any).

4. Click Options and set search options as required.

5. Click Find.

6. When XMetaL Author finds an occurrence of the text, do one of the following:

• Click Replace to replace the selected occurrence of the specified text• Click Replace All to replace all occurrences of the specified text

XMetaL | Finding and replacing text | 61

Find and replace text within a specified element




4. Click Options.

5. In the Within Element list box, choose the element to which you want to restrict the search. Set additionalsearch options as required.

6. Click Find.


• Click Replace to replace the selected occurrence of the specified text• Click Replace All to replace all occurrences of the specified text

Find and replace text with an entity reference



3. In the Replace with box, type the entity reference that you want to use to replace text.

Remember to include the opening ampersand (&) and closing semi-colon (;), for example &ProductName;.

4. Click Options.

5. Enable the Replace with entity option. Set additional search options as required.

6. Click Find.


• Click Replace to replace the selected occurrence with the specified entity reference• Click Replace All to replace all occurrences of the specified text with the specified entity reference

Repeat the last search

1. Click Edit ➤ Find Next.

Searching for elements

You can search for a specific element in your document, and replace it with a different element if doing sodoes not invalidate the markup. The element content does not change.You can also limit the search to ele-ments that occur within a specific parent element. For example, you might want to search for Para elementsthat occur inside an LI element.

You can select an element in the Element tab of the Find and Replace dialog. All elements defined in yourDTD or Schema are listed here.

62 | XMetaL | Finding and replacing text

Searching for attribute values

You can search for elements with specific attribute values by following the element name with a space-sepa-rated list consisting of attribute names followed by an equals sign (=) and a value in double quotes (" "). Forexample:

<p translate="yes">

searches only for those p elements that have a translate attribute value of ‘yes’.

Replacing attribute values

You can specify replacement attribute values. For example, to change <p translate="yes">, type the fol-lowing in the Replace with field:

<p translate="no">

If a found element has more than one attribute value set, only those that are specified in the replacementtext are modified.

Removing an attribute

If you need to remove an attribute, you have the following options:

• Delete the attribute value in the Attribute Inspector to remove the attribute. If the value is currently set to anull string, enter a new temporary value, press Enter, and then delete the value using the Attribute Inspector.

• Switch to Plain Text view and modify the XML source directly. In Plain Text view, Find and Replace expectsan exact character for character match when peforming a find and replace. Also, attribute order in the XMLsource is important.

Find and replace elements


2. Click the Element tab.

3. In the Find list box, choose the element that you want to find.

4. In the Replace with box, type or select the replacement element (if any).

5. Click Options and set additional search options as required.

6. Click Find.

7. When XMetaL Author finds an occurrence of the element, do one of the following:

• Click Replace to replace the selected occurrence of the element• Click Replace All to replace all occurrences of the element

Searching for entities

You can search for an entity reference and replace it with a different entity reference or with text.You canalso restrict your search so that you find the entity reference only when it occurs within a specific element.


Find and replace an entity reference


2. Click the Entity tab.

3. In the Find box, type the entity reference that you want to find.


Note: The search is case-sensitive.

4. In the Replace with box, type the replacement entity reference (if any).

5. Click Options and set search options as required.

6. Click Find.

7. When XMetaL Author finds an occurrence of the entity reference, do one of the following:

• Click Replace to replace the selected occurrence of the specified entity reference• Click Replace All to replace all occurrences of the specified entity reference

Find and replace an entity reference with text


2. Click the Entity tab.

3. In the Find box, type the entity reference that you want to find in the current document.



5. Click Options to expand the dialog box.

6. Enable the Replace with text option and set additional search options as required.

7. Click Find.

8. When XMetaL Author finds an occurrence of the entity reference, do one of the following:

• Click Replace to replace the selected occurrence of the specified entity reference• Click Replace All to replace all occurrences of the specified entity reference

Using search patterns

If the Use Pattern Matching option is enabled, the characters in the Find box are interpreted as patterns.Thatis, the search text can contain special search characters that match a class of text strings, or markup constructs.(If your search text does not contain any special characters, the text is searched for exactly as entered.) Thefollowing special characters can be used:

. * ? + ^ $ [ ]

In addition, the character < is used to indicate an element search when it appears as the first character in thepattern.


To search for any special character as ordinary text when Use Pattern Matching is turned on, precede it witha backslash (\). For example:

\.

matches a period.

Search patterns can be grouped by enclosing them in parentheses.

Note: Pattern matching is similar to some forms of regular expressions, but is not modeled after a specificregular expression syntax.

Search pattern summary

ExampleMatchesExpression

“abc” matches “abc”itselfordinary character

the element name<name or <name>

the entity name&name or &name;

“fo.d” matches “food”any single character.

“l*ama” matches “llama”0 or more occurrences of the char-

acter x

x*

“b(an)*a” matches “banana”0 or more occurrences of the pattern(pattern)*

“be+n” matches “been”1 or more occurrences of the char-

acter x

x+

“b(an)*a” matches “banana”1 or more occurrences of the pattern(pattern)+

“colou?r” matches “color” and “colour”0 or 1 occurrences of the character

x

x?

“b(an)*ale” matches “banale” or “bale”0 or 1 occurrences of the pattern(pattern)?

“(love|money)” matches “love” or “money”pattern1 or pattern2pattern1 | pattern2

“^Note” matches “Note” at the start of a paragraph (as

in <p>Note...</p>)

pattern immediately following

markup

^pattern

“sub$” matches “sub” at the end of a paragraph (as in

<p>...sub</p>)

pattern immediately before markuppattern$

“t[ai]n” matches “tan” and “tin”any single character in the string[string]

“th[^e]n” matches “than” , but not “then”any single character not in the string[^string]

“[a-c]” matches “a”, “b”, or “c”any character in the range[char1-char2]

“[^a-c]” matches none of the characters “a”, “b”, or “c”any character not in the range[^char1-char2]


ExampleMatchesExpression

If the search text is “(.)read” and the replace text is

“\1ox”, the result is “box”

in a replace string, it is replaced by

the text matched by the nth sub-

expression in brackets in the search

string

\n

If the search text is “fish” and the replace text is “gone

\0ing”, the result is “gone fishing”

in a replace string, it is replaced by

the text matched by the entire search

string

\0


Working with lists

If XMetaL Author has been customized to recognize list elements in your DTD or rules file, or if you are usingDITA, you can take advantage of special list editing capabilities.

Documents can contain the following kinds of lists:

• Numbered lists

• Bulleted lists

• Definition lists

You can insert numbered and bulleted lists, nest lists (insert a list inside an existing list), convert a list itemto a nested list, convert a group of paragraphs to a list and vice-versa, and convert a list from one type toanother.

Insert a list

1. In the document, click where you want to insert a list.


• If you are working in a DITA document, click Insert ➤ List and select a list type.

• Click or on the Formatting toolbar

Tip: If the contents of the list item are not surrounded by a sub-element such as a paragraph, youcan press Enter in a list item to insert a new list item after the current one. If the contents are surroundedby a sub-element, then you must press Enter twice to create a new list item.

Tip: To terminate a list, press Enter twice. If you are already in an empty list item, you have to pressEnter only once. If the list item contents are surrounded by a sub-element, press Enter three times.

Insert a list itemYou can add list items to lists you have previously created.

1. Position the cursor at the location in the list where you want to insert a list item.


• Click Insert ➤ List Item and select a list type• Press Enter

Insert a list within a listThis creates a new list of the same type as the original list, inside the original list item.

1. Create a new list item after the current one (by pressing Enter, for example).

XMetaL | Working with lists | 67

2. Press Tab.

You can edit this list as you would any other list. To terminate this list and create a new sub-list, pressEnter twice. To return to the original list, press Enter again (the new sub-list is deleted, unless it has somecontent).

Convert existing list items to a nested list

1. Highlight the list item(s) that you want to put in a nested list.

2. Press Tab.

Convert paragraphs to a list

1. Select one or more paragraph elements.


• If you are working in a DITA document, click Insert ➤ List and select a list type

• Click or on the Formatting toolbar

Convert list items to paragraphsThis converts the selected list item(s) into one or more instances of the first valid paragraph element.

1. Select one or more list items.

2. Press Shift+Tab.

Convert one type of list to another

1. Click anywhere inside the list.

2. Click Numbered List or Bulleted List on the Formatting toolbar.

Definition listsDefinition lists are a special kind of list because instead of consisting of ordinary list items, they consist of acombination of terms and definitions.

A basic definition list consists of alternating terms and definitions, but you can also have several terms ordefinitions in sequence. Of course, you do not have to use this kind of list just for definitions: you can use itfor any purpose that is suited to two-part lists.

If XMetaL Author has been configured to recognize one or more elements in your DTD as definition lists, orif you are using DITA, you can take advantage of various editing features.

68 | XMetaL | Working with lists

To insert a definition list, use the Element command in the Insert menu. The following editing shortcuts areavailable:

• To demote one or more terms or definitions to a sub-list, select them and press Tab.

• To promote a sub-list up one level to its containing list, select its contents and press Shift+Tab.

If you are using DITA, you can insert a definition list by clicking Insert ➤ List.

XMetaL | Working with lists | 69

Working with images

You can insert images into an XML or SGML document if XMetaL Author has been configured to recognizeone or more elements in the DTD as image elements. If you are working in DITA, you can insert an imageor a figure with a title through the Insert menu.

Every image element has an attribute that represents the image file. There are two ways to do this:

• The image file can be expressed explicitly as a filename or URL.

• The image file can be represented by a graphic entity. In SGML files, graphic entity references are ofteninserted by being assigned to an attribute.

Depending on your customization, you can use the following attributes to express image properties:

• Source File. This is the attribute that contains the image file name and path.

• Height. The attribute assigned to this property specifies the height of the image.

• Width. The attribute assigned to this property specifies the width of the image.

• Alternate Text. This property refers to the text that is displayed when the image file is unavailable or inbrowsers that cannot display the image itself.

• Vertical alignment. This property refers to the alignment of an inline image relative to the text on eitherside of it. For example, if the vertical alignment is set to the bottom, the bottom of the inline image lines upwith the bottom of the text on either of side of it; if the vertical alignment is set to the top, the top of theimage lines up with the top of surrounding text.

The names of the attributes used to express these properties vary from customization to customization.

For information on specifying these properties in your customization and automatically setting their values,see the XMetaL Customization Guide.

Note: If your DTD declares the element HTML:IMG, XMetaL Author recognizes it as an image elementin XML and SGML documents. The DTD should declare for HTML:IMG at least the common attributesof the HTML IMG element: SRC, ALT, HEIGHT, and WIDTH.

Insert an imageYou can insert an image into your document through the Insert menu.

1. Click Insert ➤ Image.

2. Choose an image file.

3. If you are working in a DITA document, specify properties as required.

Note: If you specify an absolute size for the image, the aspect ratio is maintained unless you enterboth a width and a height.

4. Click OK.When you insert an image in a DITA document, XMetaL inserts an <image> element. Alternative text (ifany is specified) is saved in the <alt> element. The <alt> element is a child of the <image> element.

70 | XMetaL | Working with images

Insert a figure with a titleYou can insert a figure with a title into a DITA document through the Insert menu. The figure includes animage and a title.

1. Click Insert ➤ Figure with Title.

2. Choose an image file.

3. Specify properties as required and click OK.

Note: If you specify an absolute size for the image, the aspect ratio is maintained unless you enterboth a width and a height.

XMetaL inserts a <fig> element that contains child <title> and <image> elements. Alternative text (ifany is specified) is saved in the <alt> element. The <alt> element is a child of the <image> element.

4. Type a title for the element in the prompt text for the <title> element.

Insert an image represented by an entity

1. Ensure that a graphic entity is defined for the image you want to insert, either in the DTD or within theDOCTYPE declaration in the document itself.

2. Click Insert ➤ Element.

3. Insert an image.

4. In the Attribute Inspector, edit the source attribute (the attribute that represents the image file) by choosingan entity from the dropdown list.

XMetaL Author automatically sets the height and width attributes (if specified by the customization).

Edit image propertiesYou can edit image properties through the Attribute Inspector. If you are using DITA, you can use the Imageor Figure Properties dialog.

1. Select an image.


• If you are using DITA, click Edit ➤ Element Properties.• Edit the attributes in the Attribute Inspector.

Note: The Alternative Text property in the Image or Figure Properties dialog displays the contentsof the <alt> element. If the <alt> element does not exist, the contents of the alt attribute aredisplayed.

Displaying imagesImages appear in the XMetaL Author and XMetaL XMAX document pane similar to how they appear in abrowser, including image size and, if applicable, transparency.

XMetaL | Working with images | 71

The following table lists the image formats that are supported in the XMetaL user interface.

Note: To see which formats are supported in output, check the documentation for the DITA Open Toolkit.

Table 1: Supported display formats

NotesFile extensionName

Only the Windows BMPformat is supported.

BMPWindows Bitmap

EPS files must contain anembedded TIFF header.

EPSEncapsulated PostScript

Only the first image in ananimated GIF is displayed.

GIFGraphic Interchange Format(Compuserve)

JPG (or JPEG, JPE, JFIF,JIF)

Joint Photographic ExpertsGroup

ICOWindows Icon

WMF files must include aplaceable header.

WMFWindows Metafile

EMFEnhanced Metafile

PNGPortable Network Graphics

Only the first image in a filecontaining multiple images isdisplayed.

TIF (or TIFF)Tagged Image File Format

PCXPC Paintbrush

TGATruevision Graphics Adapteror TARGA

Requires installation of anSVG viewer (for example,Adobe SVG Viewer).

SVGScalable Vector Graphics

72 | XMetaL | Working with images

Working with tables

XMetaL Author supports the CALS table model and the HTML table model. DITA supports the CALS tablemodel only. If you are working in a DITA document, you can insert a CALS table, a simplified version of theCALS table, or a topic-specific table.

If the table model in your document (as defined in your DTD or schema) fits either of these models, you canuse the commands in the Table menu to insert and edit a table in Normal and Tags On view. XMetaL Authordoes not support both table models in the same DTD or schema.

You can use the commands in the Table menu to insert and edit a table in Normal and Tags On view. Tableediting operations include:

• Editing an existing table by adding, deleting, moving, or resizing rows and columns

• Editing individual cells in a table by merging, splitting, or contracting them

• Moving or copying blocks of cells from one part of a table to another or from one table to another

XMetaL provides keyboard shortcuts for navigating in a table. Appropriately formatted content from otherapplications can be pasted or dragged and dropped into an XMetaL document as a table.

You can choose to display or hide table grid lines for tables that do not have set borders through the Viewmenu.

If you are working in a DITA document, you can choose from the following types of tables:

• Normal table. The default CALS-based table model. Provides extensive control of display and structure.

• Simple table. A simplified version of a Normal table that allows fewer elements and less control over display.

• Properties table. For use in Reference topics. Gives a list of properties for the subject of the current topic.

• Step choices table. For use in Task topics.

You can restore the structure of a simple table, properties table, or step choices table (for example, afterbackspacing and removing a cell) by clicking Table ➤ Repair Table Structure.

HTML tablesIf your DTD or schema declares the <TR> and <TD> elements as part of its table model, XMetaL Authorassumes the HTML model. These elements are recognized in upper, lower, or mixed case.

You can set HTML table formatting properties (that is, properties that apply to the whole table and not justindividual rows, columns, or cells) from the Insert Table dialog box when you insert a table.You can also usethe Table Properties dialog box at any time to change table formatting, or to set the properties of individualcolumns, rows, and cells.

Only the most common table properties are available in the Insert Table and Table Properties dialog boxes.You can set other table properties by editing the attributes of the table.

You can also add a title (called a table caption) to your HTML table.

You can nest HTML tables by putting the cursor inside a table cell and inserting a new table.

XMetaL | Working with tables | 73

HTML table propertiesYou can set table, column, row, and cell properties through the Table Properties dialog.You can set othertable properties through the Attribute Inspector.

Note: Depending on how the HTML table model is set up in your document DTD or schema, someproperties may not be available.

Note: Changing some of the table properties may not yield visible changes to the tables, although theunderlying XML content does change.

PropertyTab

Background colorTable

Table width

Border

Border width

Cell spacing

Cell padding

Background colorColumn

Column width

Vertical alignment

Horizontal alignment

Cell type

Background colorRow

Row height

Vertical alignment


Cell type

Background colorCell

Row height

Cell width

Vertical alignment


Cell type

Insert a table caption

1. Click anywhere inside the table.

2. Click Table ➤ Insert Caption.

3. Type the caption text.

4. Optional: Set the position of the caption through the Attribute Inspector.

By default, browsers display the caption above the table. If you select the BOTTOM option for the ALIGNattribute, the caption continues to appear above the table in XMetaL Author, but appears centered belowthe table in most browsers.

74 | XMetaL | Working with tables

Edit a table caption


2. Click Table ➤ Select Caption.

3. Make the required changes to the caption text.

4. Optional: Change the position of the caption through the Attribute Inspector.

By default, browsers display the caption above the table. If you select the BOTTOM option for the ALIGNattribute, the caption continues to appear above the table in XMetaL Author, but appears centered belowthe table in most browsers.

CALS tablesIf your DTD or schema declares the <TGROUP> element as part of its table model, or if you are working in aDITA document, XMetaL Author assumes the CALS model. The CALS Table Model DTD is defined by theOASIS organization.

CALS tables can consist of three parts: a table header, the table body, and a table footer.You can insert aheader and footer when you insert the table, or you can edit an existing table to set rows as header and footerrows. Although headers and footers are optional, their position is not. Headers are always the top row(s) ofthe table, and footers are always the bottom row(s) of the table. If you want to add a header or footer afterinserting the table, you must use the Row tab of the Table Properties dialog box.

You can insert a CALS table with a maximum of 150 rows and 150 columns. If you specify more than 150rows or columns, no error message appears, but the new table contains only 150 rows or columns. If youneed a table with more than 150 rows or columns, you can add the required rows or columns to the tableafter you create it.

You can nest CALS tables by putting the insertion point inside a table cell and inserting a new table. TheCALS model as defined by OASIS calls for tables to be nested to one level only; however, depending on thestructure of your DTD, you may be able to nest more than one level in your CALS table. Nested CALS tablesconsist of a table body and an optional table header.

You can set CALS table formatting properties for the entire table as well as for individual rows, columns, andcells from the Table Properties dialog box.

CALS table propertiesXMetaL Author supports the following table, column, row, and cell properties in CALS tables.

Note: Changing some of the table properties may not yield visible changes to the tables, although theunderlying XML content does change.

PropertyTable element

FrameTable

Column separator

Row separator


NameColumn

Column width


PropertyTable element

Column separator

Row separator


Row separatorRow

Vertical alignment

Row type

Column separatorCell

Row separator


Vertical alignment

Proportional column widths

A column width can be a specific value such as 2 in, or a proportional value. A proportional value is expressedas a number followed by an asterisk (*), for example, 2*. The numbers associated with each proportionalwidth are combined to form a ratio that describes how portions of the total table width are distributed amongall the columns that have proportional widths (after all columns that have specific widths get their share).Thedefault column width is 1*.

For example, suppose your table has four columns and a width of four inches, and the column widths arespecified as 1*, 2*, 3*, and 1in. The widths of the four columns are calculated as follows: the fourth columnhas a width of one inch, because its width is specified explicitly. This leaves three inches to be distributedamong the other three columns according to the ratio 1:2:3 (that is, the second column is twice as wide asthe first column, and the third column is three times as wide as the first). This means that the first column is0.5 inches wide, the second column is 1.0 inches wide, and the third column is 1.5 inches wide.

Insert a tableYou can insert an HTML or CALS table using the Table menu. You can insert different kinds of tables,depending on the requirements of the content and the topic type.

1. Click Table ➤ Insert Table.

2. (CALS tables only) Choose the Table Type (the top-level table element).

Not all types of tables are available in all topic types; if you are prevented from inserting a certain type oftable, it is because the topic type does not allow it.

3. Enter the number of rows and columns for the table.

4. Indicate whether or not to add an extra row at the top designated as the header row.

Format a table


2. Click Table ➤ Table Properties.


3. Click the Table tab.

4. Set table properties as required.

Format a column

1. Click anywhere in the column you want to modify.


3. Click the Column tab.

4. (CALS tables only) Type a name for the column.

Every column in a CALS table can be given a name. If a column name is present, it must be unique withinthe current table.

5. Set column properties as required.

Format a row

1. Click in the row you want to modify.


3. Click the Row tab.

4. Set row properties as required.

Tip: You can change a body row to a header row or vice-versa using the Row type options.

Format a cell

1. Click inside the cell you want to modify.


3. Click the Cell tab.

4. Set cell properties as required.

Format a selection of cells

1. Select the cells you want to edit.

You can select any block of cells in a table: a single cell, a row or column, several adjacent cells in a rowor column, or a block spanning two or more rows and columns.


3. Click the Selection tab.

4. Set selection properties as required.


Navigating within a table

There are several ways to move the cursor within a table:

• You can move up, down, left, and right using the arrow (cursor) keys.• Clicking to the right of a table moves the insertion point outside of the table. This is particularly useful in

Normal view when the table is at the bottom of the document.• To move to the next cell on the right, press Tab. If you press Tab in the last cell in a row, the insertion point

moves down to the first cell in the next row. (If you press Tab in the last cell in the table, a new row isinserted at the bottom of the table.)

• To move to the next cell on the left, press Shift+Tab. If you press Shift+Tab in the first cell in a row, thecursor moves up to the right-most cell in the previous row.

• To move to the last cell in the current row, press Alt+End.• To move to the first cell in the current row, press Alt+Home.• To move to the last cell in the current column, press Alt+PageDown.• To move to the first cell in the current column, press Alt+PageUp.

If a cell spans two or more columns, the cell is considered to be contained in the left-most of those columnsfor purposes of navigation. If a cell spans two or more rows, the cell is considered to be in the topmost ofthose columns for purposes of navigation.

Because the Tab key is used for table navigation, if you want to insert the tab character itself in a table cell,you have to record the action of inserting a tab in a macro, and then use the macro to insert the tab. How?

Enter a tab character in a table cell

1. Switch to Plain Text view.

2. Click in a location where text is allowed.

3. Click Tools ➤ Record New Macro.

4. Press Tab.

5. Click Tools ➤ Stop Recording.

6. Complete the macro.

7. Switch back to Normal or Tags On view.

8. Click inside a table in a PRE-like sub-element, in which whitespace is preserved.

9. Run the macro.

Editing table rows and columns

You can edit table rows and columns in these ways:

• Add rows and columns to an existing table.

• Delete rows and columns.

• Move rows up or down by one row.

• Move table columns left or right by one column.

• Change the size of rows and columns.


Insert rows or columns

1. Click in a row or column next to where you want to insert the new rows or columns.

2. Click Table ➤ Insert Rows or Columns and select an option.

3. Type the number of rows or number of columns.

Delete a row from a table

1. Click anywhere in the row that you want to delete.

2. Click Table ➤ Delete Row.

Delete columns from a table


• Click anywhere in the column that you want to delete• Select a block of cells that spans the columns you want to delete

2. Click Table ➤ Delete Column.

Note: If you choose Delete Column while an entire row is selected, the entire table is deleted(because all columns have been selected).

Move a table row or column

1. Click anywhere in the row or column that you want to move.

2. Click Table ➤ Move Row or Column.

3. Choose an option.

Resizing rows and columns

In HTML tables, you can resize rows and columns from the Table Properties dialog box or by dragging therow and column boundaries in the document pane. In CALS tables, only columns can be resized.

Tip: You can change the width of a column without affecting the width of any other columns in the tableby holding down the Shift key while you drag the right edge of the column to the desired width.

Change the height of a rowYou can specify the height of a row in an HTML table.

1. Click anywhere inside the row that you want to resize.


3. Click the Row tab.

4. Type the height, in pixels, in the Row height box.


Change the width of a column

1. Click anywhere inside the column you want to resize.


3. Click the Column tab.

4. Enter a column width.

Editing table cells

You can edit table cells by splitting one cell into two, merging two cells into one, or contracting a cell thatspans more than one row or column.

Splitting a cell means dividing one cell into two, either vertically (splitting into columns) or horizontally (splittinginto rows).

Merging cells means combining two adjacent cells into one cell.

Contracting a cell in a table pulls the boundary of a cell one cell to the left, right, top, or bottom and inserts acell where the boundary was pulled back.You can only contract cells that span more than one row or column.

Split a cell vertically

1. Click anywhere in the cell that you want to split.

2. Click Table ➤ Split Cell into Columns.

If the original cell had any content, it is located in the left column after the split.

Split a cell into two rows

1. Click anywhere in the cell that you want to split.

2. Click Table ➤ Split Cell into Rows.

If the original cell had any content, it is located in the upper row after the split.

Merge adjacent cells

1. Click anywhere in one of the cells that you want to merge.

2. Click Table ➤ Merge Cell.

3. Select a merge option.

4. Click OK.

The merge succeeds even if the current cell spans across two or more rows or columns. The reverse isnot true, however: if the cell that the current cell is being merged with extends over more rows or columns(or a different set of rows or columns) than the current cell, the merge fails, and an error message appears.

Contract a cell spanning two or more rows or columns

1. Click View ➤ Toolbars and select Table Advanced.

2. Click anywhere in the cell that you want to contract.


3. Click one of these buttons on the Table Advanced toolbar:

Contract Cell From Left. Pulls the left boundary of the active cell one cell to the right and inserts an

empty cell in the space created. Contract Cell From Right. Pulls the right boundary of the active cell

one cell to the left and inserts an empty cell in the space created. Contract Cell From Bottom. Pulls

the bottom boundary of the active cell one cell up and inserts an empty cell in the space created.Contract Cell From Top. Pulls the top boundary of the active cell one cell down and inserts an emptycell in the space created.

Moving and copying table cells

In both HTML and CALS tables, you can select a rectangular block of cells and then move or copy the contentto another block containing the same number of cells.

The target location must have at least as many cells block of cells to which you want to copy or move cellcontent must be the same configuration as the block of cells you are copying or moving.

If you are copying and pasting to another document, both documents must conform to the same DTD, schema,or rules file.

Move a block of cells

1. Select the block of cells that you want to move.

You can select any rectangular block of cells in a table: a single cell, a row or column, several adjacentcells in a row or column, or a block spanning two or more rows and columns.

2. Click Edit ➤ Cut.

3. Click inside the cell that marks the upper left corner of the location where you want to paste the cell content.

4. Click Edit ➤ Paste.

Note: The move operation does not create new cells within the target table. Any content in the targetcell block is overwritten with the pasted content.

Note: You can also drag and drop your selected block of cells to its new location.

Copy a block of cells

1. Select the block of cells that you want to copy.

You can select any rectangular block of cells in a table: a single cell, a row or column, several adjacentcells in a row or column, or a block spanning two or more rows and columns.

2. Click Edit ➤ Copy.

3. Click inside the cell that marks the upper left corner of the at the location where you want to copy the cellcontent.

4. Click Edit ➤ Paste.

The selected content appears in its new location in the table.

Note: The paste operation does not create new cells within the target table. Any content in the targetcell block is overwritten with the copied content.


Note: You can also copy your selection by holding down the Ctrl key while you drag and drop theselected block of cells to its new location.

Inserting tables from other applications

If your DTD supports tables, you can copy and paste content from other applications, such as spreadsheetsand text editors, into XMetaL Author. This material is inserted as an HTML or CALS table, according to theformat supported by the DTD or schema.

XMetaL Author converts a pasted selection into a table if all of these conditions are met:

• There are at least two lines.

• Each line consists of items separated by tabs.

• Each line has at least two items.

• Each line has the same number of items. This does not mean that every cell in every line has to havecontent. To represent an empty cell, enter a tab to indicate that the cell is there, even though it is empty.

Selections from spreadsheets such as Excel are normally represented in the format described, so there isno problem with pasting them. Material from text editors such as Notepad can also be pasted, and is automat-ically converted into a table as long as it conforms to the above guidelines.


Marking changes to text

A document may be subject to changes and revisions from more than one author in a variety of scenarios,such as part of an XMetaL Reviewer project, or through less formal ad hoc changes. It often useful for authorsand reviewers to be able to quickly spot the changes made since they last viewed the document. Also, theymay want to be able to tell which person made which changes.

You can set XMetaL Author so that changes made to text in a document appear as marked insertions ordeletions. When change tracking is active, text that is inserted in a document appears in a different color thanthe existing text. It may also have additional formatting applied to it.Text that has been deleted can be hidden,or can remain visible in the document, but in a different color and with a line through it to signal that it hasbeen deleted. The default settings show insertions as red underlined text, and deletions as blue text withstrikethrough marking applied, but you can change the color for both insertions and deletions, or you can setXMetaL Author to use different colors for different contributors’ additions and deletions.You can also changethe additional text formatting for insertions.

When you rest the mouse pointer over text that has been marked as changed, a popup, or tooltip, displaysthe name of the user who made the change, the nature of the change (insertion or deletion), and the datethe change was made.

Changes XMetaL Author can track

• Text inserted or pasted in Tags On or Normal view.

• Text deleted or cut in Tags On or Normal view.

• Text moved by dragging and dropping in Tags On or Normal view.

Changes XMetaL Author does not track

• Changes to markup, including elements that are split or joined.

• Changes to attribute values.

• Addition of entity declarations.

• Addition or deletion of rows and columns in tables.

• Any changes made in Plain Text view.

Track changes

1. Open the document you want to edit in Tags On or Normal view.

2. Click Tools ➤ Track Changes.

Note: Turning change tracking off does not accept, reject, or hide any changes made while changetracking was on.

XMetaL | Marking changes to text | 83

Move between tracked changes

1. Open the document in Tags On or Normal view.

2. In the Reviewing toolbar, click Next Change or Previous Change .

Accepting or rejecting tracked changes

You can use the Accept or Reject Changes dialog box to accept or reject all changes, or accept or rejecteach change individually. When marked changes are accepted, the changes are incorporated into the doc-ument, and the revision marks are removed from the relevant text. When marked changes are rejected, thechanges are removed, and the deleted text (if any) is restored to the document.

Accept or reject tracked changes

1. Open the document in Tags On or Normal view.

2. Click Tools ➤ Accept or Reject Changes.


• Accept or reject all changes in the document at once by clicking Accept All or Reject All• Accept or reject changes one at a time by clicking Find Next or Find Previous and clicking Accept

or Reject

Note: When Rules Checking is active, XMetaL Author does not reject changes that are necessaryto make the document valid.

84 | XMetaL | Marking changes to text

Using the writing tools

XMetaL Author includes writing tools that you can use to check spelling and search for alternative words.You can also create lists of special words or acronyms that you do not want the spell checker to flag.

The writing tools are available in English, French, and German.

Checking your spelling

You can use the spell checker to check your text in many ways:

• Check the spelling in an entire document, part of a document, or only selected text.

• Manually edit text and then resume checking the document.

• Ignore a spelling error once but flag subsequent occurrences of the problem, or ignore the error for the restof the proofreading session.

• Replace words by choosing a word from a list of available words, by typing in the correct word, or by definingan automatic replacement for a word (especially useful for words that are regularly misspelled).

You can also choose the spell checking language and customize how the spell checker checks spelling in adocument. For example, you can choose how the spell checker starts and whether it searches for misspelledwords, irregular capitalization, duplicate words, and words with numbers.

Note: The spell checker does not check the spelling of processing instructions, comments, hiddenelements, entity references, or form fields.

Check spellingYou can check the spelling of an entire document or a selection.

1. Click Tools ➤ Spell Checker.

2. Make a selection from the Check list box.

3. Click Start.

4. When checking stops at a misspelled word, choose a word from the Replacements box or type thereplacement in the Replace with box.


• Click Replace to replace the current word• Click Auto Replace to replace all occurrences of the word in the document

Ignore a flagged word


2. Make a selection from the Check list box.

3. Click Start.

4. When checking stops at a word you do not want to change, do one of the following:

• Click Skip once

XMetaL | Using the writing tools | 85

• Click Skip all (and add that word to the user word list for the document)

Using spell checker word lists

The spell checker checks spelling by comparing words in your document with the words in one or more listsof acceptable words.

There are two types of word lists: main word lists, and user word lists. When the spell checker is checking aword in your document, it always looks in the user word lists first and the main word lists second.

Working with main word lists

Main word lists are the built-in word lists included with the writing tools. The availability of word lists is deter-mined by the options you select when you install XMetaL author.

The default main word list is determined by the spell checking language or language variant you select.

You can use more than one main word list to spell check your document. For example, if you want the spellchecker to use both English and French main word lists, you can add whichever of these main word lists isnot the default. Any word lists that you add in this way can also be removed.

Add a main word list


2. Click Options ➤ Main Word Lists.

3. Click Add List.

4. Select the main word list you want to add.

5. Click Open.

Remove a main word list


2. Click Options ➤ Main Word Lists in the menu that appears.

3. Click the main word list that you want to remove.

4. Click Remove List.

Working with user word lists

User word lists are unique to your XMetaL Author setup or document.You can add words or expressions toa user word list, and specify whether you want the spell checker to skip them, replace them with a differentword automatically, or suggest alternatives for them. For example, you can specify replacements for wordsthat you frequently misspell or mistype, or you can add words that you do not want the spell checker to flag.

86 | XMetaL | Using the writing tools

User word list files have the extension .uwl. The word list that is installed by default is WT10xx.uwl (wherexx is the two-letter code for the language or language variant you are using for spell checking). This file isavailable to any document created or edited in your setup of XMetaL Author. If you have more than one ofthese lists installed on your system, you can add or remove them from the set of word lists that the spellchecker uses for your document.

In addition to the default word list, each document has its own word list. Any time you ignore a word duringspell checking by clicking Skip All, that word is added to the document user word list.

Set the default user word list


2. Click Options ➤ User Word Lists.

3. In the User Word Lists dialog box, click a word list.

The spell checker uses the rules and exceptions on this word list before it uses the other user word list(s)or the main word list(s).

4. Click Set Default.

Add a user word list



3. Click Add List.

4. Select the user word list you want to add.

5. Click Open.

Add an entry to a user word list



3. Click the word list to which you want to add an entry.


• Type the word in the Word/phrase box• Add a misspelling or a phrase that you want the spell checker to replace automatically and type the

replacement in the Replace with box

5. Click Add Entry.

Delete an entry from a user word list



3. Choose a word list.

4. Click the entry you want to delete.

5. Click Delete Entry.


Change the replacement text for an entry in a user word list



3. Click a word list.

4. Click the entry you want to change.

5. Edit the text in the Replace With box.

6. Click Replace Entry.

Change an entry in a user word list



3. Click the word list that contains the entry you want the spell checker to handle differently.

4. Cick the entry you want to change.

5. Click Properties.

6. Choose an option in the Entry type area:

• Skip word. Enable this option if you do not want the spell checker to flag the word as incorrect.• Auto-replace entry. Enable this option if you want the spell checker to automatically replace any

instance of the word or phrase in your document with the Replace with text.• Exception entry. Enable this option if you have multiple Replace with entries for one word and you

want the spell checker to ask you which replacement text to use when it encounters the word in adocument.

7. Edit the text in the Word/Phrase box as required. This is the text that the spell checker finds (or ignores).

8. Edit the text in the Replace with box as required.

If you want to enter more than one choice for replacement text (for Exception entry types), each choicemust be on a separate line in the Replace with box.

9. Click OK.

Note: If the Auto-replace entry option is enabled, any text in the Replace with box is ignored.

Using the thesaurus

XMetaL Author includes a thesaurus, which you can use to refine your word choices.The thesaurus is availablefor English, French, or German, depending on options selected during installation.

You can look up a word in your document and display synomyms, antonyms, and other related informationfor that word.

You can also choose the data file that the thesaurus uses to look up words.

Look up a word in the thesaurus

1. Click Tools ➤ Thesaurus.

2. Type the word you want to look up in the list box at the top of the Thesaurus page.


3. Click Look up.

4. Expand the desired definition to display a list of synonyms and other related words.

Note: To see more information about a related word, double-click the word you are interested in. Asecond list box opens containing the thesaurus entry for the word you double-clicked.

Replace a word using the thesaurus

1. Select the word you want to replace.


3. Click Look up.


5. Click the word you want to use to replace the original word in the document.

6. Click Replace.

Note: The thesaurus may prompt you to select the correct form of the word you want to insert. Thishappens when you want to replace a word that is the same in the present or past tense (such as“read”) or a word that can be used as more than one part of speech (for example, “wonder”, whichcan be used as either a noun or a verb).

Insert a word from the thesaurus


2. Type the word you want to look up in the list box at the top of the Thesaurus page.

3. Click Look up.


5. In your document, click where you want to insert the word.

6. Click the word you want to insert.

7. Click Insert.

Note: The thesaurus may prompt you to select the correct form of the word you want to insert. Thishappens when you want to replace a word that is the same in the present or past tense (such as“read”) or a word that can be used as more than one part of speech (for example, “wonder”, whichcan be used as either a noun or a verb).

Set thesaurus options


2. Click Options.

In the menu that appears, click the following commands to enable or disable them:

• Auto look-up. Enable this option to automatically display the thesaurus entry for the word that containsthe cursor at the time the thesaurus is opened.

• Auto close. Enable this option to close the Writing tools dialog box automatically when you insert a wordfrom the thesaurus into your document.

• Spelling assist. Enable this option to have the thesaurus suggest alternate spellings if the word you wantto look up is spelled incorrectly or not found in the thesaurus.

Options with check marks beside them are currently enabled.


Any options you change remain in effect the next time you open the Thesaurus.

Set thesaurus look-up options


2. Click Options. In the menu that appears, click the following commands to enable or disable them:

• Synonyms. Choose this option to display words that have the same or similar meaning as the wordbeing looked up.

• Antonyms. Choose this option to display words that have an opposite meaning.• Related Words. Choose this option to display words that have similar meanings, but are not as close

as synonyms.• Is a type of. Choose this option to display words for items or ideas that include the word being looked

up. For example, if the selected word is “tree, this list might contain the word “plant”, because a tree isa type of plant.

• Has types. Choose this optin to display words whose meaning is a subset of the word being looked up.For example, if the selected word is “tree”, this list might contain the words “evergreen”, because onetype of tree is an evergreen tree.

• Is a part of. Choose this option to display words for items or ideas for which the word being looked upis a component. For example, for the selected word “tree”, this list might contain the word “forest”.

• Has parts. Choose this option to display words for items or ideas that are a component of the word beinglooked up. For example, for the selected word “tree”, this list might contain the word “branch”.

• Example. Choose this option to display a sample phrase illustrating the correct use of the word.

Options with check marks beside them are currently enabled, and appear in the look-up list box whenthey are included in a thesaurus entry for the word being looked up.

Note:

• Any options you change remain in effect the next time you open the Thesaurus.• Depending on the thesaurus language chosen, some look-up options may not be available.• If a look-up option has been enabled but the feature does not appear in the list box when you look

up a specific word, it means that entry in the thesaurus does not include the feature. Most thesaurusentries include only some of the look-up options.

Set the thesaurus data file


2. Click Options ➤ Set Data File.

3. Select from the following data files:

• wt10uk.ths. British English• wt10us.ths. American English• wt10de.ths. German• wt10fr.ths. French

4. Click Open.

Note: Which data files are actually available depends on the options that were chosen when XMetaLAuthor was installed. If the data file you want to select is not available, you must reinstall XMetaLAuthor and specify different language options as part of the installation wizard. See install_readme.htmlon the XMetaL Author CD for more information.


Specifying the language settings

XMetaL Author supports four variants of English (British, American, Canadian, and Australian), two variantsof French (French national and Canadian), and two variants of German (German national and Swiss).Youcan choose a language for the current file or set it as the default language for all of the writing tools.You canalso add and remove languages in the spell checker and the thesaurus.

All included languages support hyphenation.

Each language has specific ways of formatting dates, time, currency symbols, and other text.You can checkfor the formatting conventions of another language. For example, the spelling checker can format all datesin a document according to specific conventions (such as “12 avril 1996” for French).

Set the language


2. Click Options ➤ Language.

3. Click the language that you want the writing tool to use.

Note: Enable the Show available languages only check box to list only those languages supportedby the current writing tool.

Add a language



3. Click Add.

4. In the Language Code box, type a two-letter code for the language you want to add.

This code must be unique, that is, it cannot already exist in the list of languages.

5. In the Description box, type the name of the language (or the language variant).

Remove a language



3. Select a language from the Language list.

4. Click Remove.

Note: You can remove only languages that have been added since installation. Languages that wereincluded when XMetaL Author was installed cannot be removed using this method. If you want toremove an installed language, you must reinstall XMetaL Author and specify different language optionsas part of the installation wizard. See install_readme.html on the XMetaL Author CD for moreinformation.


Setting spell checker options

You can specify the following spell checker options through the Spell Checker menu in the Tools menu.Yoursettings are applied the next time you open the spell checker.

DescriptionOption

Starts spell checking automatically from thebeginning of the document when you openthe spell checker.

Auto start

Sounds an alert when the spell checker findsa word it does not recognize.

Beep on misspelled

Re-checks all spelling from the beginning ofthe document when you interrupt the spellchecker and then press Resume.

Recheck all text

Checks for words that contain numbers (forexample, postal codes).

Check words with numbers

Checks for duplicate words.Check duplicate words

Checks for incorrect capitalization (forexample, two uppercase letters at thebeginning of a sentence).

Check irregular capitalization

Asks for user input before replacing a word.Prompt before auto replacement

Suggests words that sound similar to a flaggedword.

Show phonetic suggestions

Setting thesaurus options

You can specify the following thesaurus options through the Thesaurus menu in the Tools menu.Your settingsare applied the next time you open the thesaurus.

Note: Most thesaurus entries include only some of the options listed below.

Table 2: General options

DescriptionOption

Displays the thesaurus entry for the currentword when the thesaurus is opened.

Auto look-up

Closes the Writing Tools dialog box after youinsert a word from the thesaurus into yourdocument.

Auto close

Suggests alternate spellings if the word isspelled incorrectly or not found in the the-saurus.

Spelling assist


Table 3: Look-up options

DescriptionOption

Displays words that have the same or similarmeaning as the word being looked up.

Synonyms

Displays words that have an oppositemeaning.

Antonyms

Displays words that have a similar meaning,but are not as close as synonyms.

Related words

Displays words for items or ideas that includethe word being looked up. For example, if the

Is a type of

selected word is tree, this list might contain“plant”.

Displays words that have meanings that area subset of the word being looked up. For

Has types

example, if the selected word is “tree”, this listmight contain “evergreen”.

Displays words for items or ideas for whichthe word being looked up is a component. For

Is a part of

example, if the selected word is “tree”, this listmight contain “forest”.

Displays words for items or ideas that are acomponent of the word being looked up. For

Has parts

example, if the selected word is “tree”, this listmight contain “branch”.

Displays a sample phrase that illustrates thecorrect use of the word.

Example


Using macros

A macro is a sequence of operations that can be run as a unit. Macros can be associated with a shortcut key,toolbar button, or menu item.This is particularly useful when you have to repeatedly execute a task that doesnot have a built-in shortcut key or command.

Macros may also perform some special functionality outside of the normal XMetaL Author functions. Suchmacros are created for you by your customizer, and are available from the Macros dialog box. Depending onthe customization, you may also be able to run them through toolbar buttons or menu commands. See yourcustomizer for details.

Macros are stored in macro files, which have the extension .mcr.You may have macros from as many asfour different macro files available to you at any one time.

Note: Some macros may be disabled for limited users under Citrix.

Restrictions on macros

A macro should be self-contained, that is, its completion must not depend on any user input at the time themacro is run.Therefore, there are some actions that cannot successfully be included in a macro. As a generalguideline, if a macro involves any of the commands that open dialog boxes, that action should be completedsomewhere in the macro. (Commands or buttons that open dialog boxes usually have an ellipsis (...) afterthe command or button name.) For example, you can create a macro that inserts a particular element, butyou cannot create a macro that simply displays the Insert Element dialog box.

Mouse clicks in the document pane are ignored during macro recording. The first time you try to use themouse to change the selection, you will hear an alert. The second time, a message appears saying that youshould use the cursor (arrow) keys to change the selection.

Not all commands can be recorded in a macro. A macro that was recorded in Normal or Tags On view canusually be played back in the other view. Macros recorded in the Plain Text view are less likely to work in theother views.

In addition to the above restrictions, the following actions cannot be recorded in a macro:

• Actions that make a different document the active document (for example, drag and drop between documents)

• Setting table properties

• Spell checking operations

• Most commands in the File and View menus

Running macros

There are several ways to run a macro:

• Select it from the Macros toolbar

• Select it from the Macros dialog box

94 | XMetaL | Using macros

• Press its keyboard shortcut combination, if one has been assigned

• Click a toolbar button or menu command, if one has been assigned

Note: You can run only one macro at a time.

Run a macro

1. Click Tools ➤ Macros.

2. Select a macro.

3. Click Run.

Recording macros

You can record a series of steps and keystrokes as a macro. Macros are stored in any of the following macrofiles:

• Global macro file for all users. Macros/xmetal.mcr contains macros available to all users for all docu-ments. This is the default macro file that loads when you start XMetaL Author.

• Global macro file for the current user only. xmetal.mcr in your personal settings folder contains macrosavailable to the current user for all documents being edited.

• DTD-specific macro file for all users. Macros/<dtdname>.mcr (where dtdname is the name of the relatedDTD), contains macros available to all users for any document based on the related DTD.

• DTD-specific macro file for current user only. dtdname.mcr in your personal settings folder (wheredtdname is the name of the related DTD), contains macros available to the current user for any documentbased on the related DTD.

DTD-specific macro files load when you open a document that uses that DTD.

Note: Some customizations may overwrite the macro files stored in the XMetaL Author program folderson a regular basis. For this reason, it is often safer to store your recorded macros in one of the two macrofiles that are saved in your personal settings folder.

Record a macro

1. Click Tools ➤ Record New Macro.

2. Perform the sequence of actions that you want the macro to execute.

These actions are not only recorded, they are also applied to the current document as you perform them.

3. Click Tools ➤ Stop Recording.

4. Select an option from the Create this macro for list.

5. Type a name for your macro in the Macro name box.

6. Optional: Specify a shortcut key combination to associate with the macro.

7. Optional: Specify an image to associate with the macro.

This image appears beside the macro name in the Macros dialog box.

XMetaL | Using macros | 95

8. Click Close.

Setting up macro access shortcuts

You can configure any macro available to you so that you can run it by pressing a combination of keys (akeyboard shortcut), or you can create a toolbar button or menu command for the macro.You can set thekeyboard shortcut at the time you record the macro.You can also change a keyboard shortcut for any macroat any time.

Set the keyboard shortcut for a macro


2. Select a macro.

3. Choose a shortcut key combination.

4. Click Close.

Associate a macro with a toolbar button

1. Display the toolbar to which you want to add your toolbar button.

2. Click View ➤ Toolbars.

3. Click the Button tab.

4. Select Application Macros or dtdname Macros (where dtdname is the name of the DTD on which thecurrent document is based) from the Categories list.

Note: If no document is open, only the Application Macros macro set appears in the list.

5. In the Macros list, select a macro.

6. Optional: Do any combination of the following:

• Choose an image to associate with the macro• Type the text you want to appear as the button tooltip• Type the text you want to appear in the status bar while the macro is running

7. Click Close.

Associate a macro with a menu command


2. Click the Menu tab.

3. Click the name of the menu or submenu to which you want to add your new command.

4. Click Add Menu Item.

5. From the Macros list in the Properties area, select the macro that you want to associate with the menucommand.

6. In the Properties area, type the name for the command as you want it to appear in the menu.

7. Optional: Do any combination of the following:

• Type the text you want to appear in the status bar while the macro is running• Enable the Begin Group option to create a separator bar above the command in the menu

96 | XMetaL | Using macros

8. Click Move Up and Move Down to position the command relative to the other commands in the menu.

9. Click Close.

Deleting macros

When you delete a macro, you remove it from the macro list on the toolbar and in the Macros dialog box, andfrom the corresponding macro file. It does not reload the next time you start XMetaL Author (unless XMetaLAuthor is customized to overwrite macro files with fresh copies from a central server every time it starts).

Delete a macro


2. Select a macro.

3. Click Delete.

XMetaL | Using macros | 97

Using the Resource Manager

The Resource Manager is an asset management tool that gives you access to many kinds of objects, orassets.You can use the Resource Manager to organize objects into categories, and then drag and drop them“intelligently” into your documents.

You can also use the Resource Manager to select different views, create filters, navigate through folders,and view images as thumbnails before you insert them into your document.

By default, the Resource Manager contains two tabs, the Assets tab and the Desktop tab, although additionaltabs can be added as part of a customization.

The Assets tab provides access to your collection of assets, which you can insert in your documents usingthe intelligent insertion operations.

The Desktop tab provides an Explorer-like view of your desktop from which you can drag and drop files intoyour document, and add your own assets to the collection in the Assets tab.

The top pane of the Resource Manager is a folder view called the Explorer pane.

The bottom pane of the Resource Manager is called the Contents pane. In this pane, you can view the contentsof the open folder in the Explorer pane, and drag and drop files into your document.

The Resource Manager toolbar appears in the Contents (lower) pane of the Desktop tab. The content of thetoolbar changes according to the type of object selected.

Assets tab

By default, the Assets tab contains the following folders:

• Customizable Asset Templates. A set of templates that can be used to create your own asset folders. Inorder to make these templates usable, you must copy them to the Asset Templates folder.

• Journalist DTD. A small set of sample assets that work with the journalist DTD.

• My Assets. A folder in which you can build up your own library of objects.

Desktop tab

The Desktop tab provides direct access to the objects on your computer’s desktop.You can use it to chooseobjects from your system to insert into your documents, or to save as part of your assets collection in theAssets tab.

You can use the Resource Manager toolbar, in the Contents pane of the Desktop tab, to navigate throughfolders, create new folders, and set view options. The content of the toolbar changes according to the type

of object selected. For example, when you click Item Menu( ) on the Resource Manager toolbar, a set ofmenus appears. The menus and commands included in this set depend on the object selected. Typically,the set of menus contains File, Edit, View, Tools, and Help menus.

98 | XMetaL | Using the Resource Manager

Inserting objects in your document

You can insert objects that have been stored as assets into your document from the Asset tab of the ResourceManager.You can also use the Desktop tab to drag into your document objects that have not been storedas assets. In general, however, to take advantage of the intellingent insert capabilities, it is best to add objectsto one of your assets folders and insert them using the Asset tab.

Insert an asset from an asset folder

1. In the Resource Manager, click the Assets tab.

2. In the Contents (bottom) pane, click and hold the asset you want to add to your document, drag it intoyour document, and do one of the following:

• If the object (for example, an image) is to be inserted at a specific location in the document, drop it atthe required location

• If the object is one that the Resource Manager inserts intelligently by generating the appropriate markup(for example, a stylesheet), drop it anywhere in the document

Insert an object from your system

1. In the Resource Manager, click the Desktop tab.

2. In the Contents (bottom) pane, click and hold the asset you want to add to your document, drag and dropit into your document at the desired location.

Creating an asset collection

You may want to build up your own collection of assets and incorporate them into the Resource Managercollection in order to take advantage of its intelligent insertion capabilities.You should store these files in theMy Assets folder.You can create your own folders within the My Assets folder to organize and categorizeobjects to insert into your documents.

The categories of assets that you can create are defined by asset templates, which are a set of folders locatedin the Asset Templates folder. A set of customizable templates is located in the Customizable Asset Templatesfolder underneath the Assets folder. If you want to make these templates available, use the Desktop tab orWindows Explorer to copy the contents of the Customizable Asset Templates folder to the Asset Templatesfolder. Most of these templates are ready for use; others (Images {Specific Tag}) need to be further customizedfor your particular DTD.

Note: You do not have access to the Asset Templates folder from the Assets tab of the ResourceManager. To see the contents of the Asset Templates folder, you must use either the Desktop tab orWindows Explorer.

Create an asset folder

1. In the Resource Manager, click the Assets tab.

2. Right-click the My Assets folder, and then click New Folder on the menu that appears.

XMetaL | Using the Resource Manager | 99

3. Type a name for the new folder in the Folder Name text box.

Note: If you are using more than one DTD, and some assets are only used with a particular DTD,consider including the name of the DTD in the folder name; for example, journalist-images ordocbook-code.

4. Choose an asset type from the Type of Assets list box to specify the types of objects (assets) you plan toput in that folder.

The asset types listed in the Type of Assets list box are determined by the template folders available inthe Asset Templates folder.

5. Click OK.

The contents of the Assets tab correspond to the XMetaL Author Assets folder. If you add a folder to thisfolder using Windows Explorer, and click the new folder in the Explorer pane of the Assets tab, the Contentspane displays a Convert to Assets page. Click Convert on this page to perform the conversion. A dialogbox appears in which you choose the Asset type and specific files to import.

Rename an asset folder

1. In the My Assets folder, right-click a folder and click Rename.

2. Type the new name for the folder, and then press Enter.

Add an asset to the My Assets folder

1. In the Resource Manager, click the Desktop tab.

2. Select an asset from the bottom (Contents) pane and drag it onto the Assets tab.

You can also drag and drop images and text or markup blocks from XMetaL Author documents intoappropriate asset folders.


• Drop the object (release the mouse key)• Navigate to the desired folder through the Explorer pane and drop the object

4. If the folder has been assigned an asset type of Assorted, a dialog box appears prompting you to selectthe type of asset the object is (for example, clip art). Enter a description for the object.

5. For certain object types, you must enter additional information, for example, alternate text for an image.Enter this information.

100 | XMetaL | Using the Resource Manager

Importing databases

If your customization allows it, you can import the contents of a database or spreadsheet file into your documentas a table.The database import feature generates an SQL query that you can view and then modify to importonly the content that you need.You can also use it to set up the appearance of the table to be created.

Most customizations include a menu command or a toolbar button that you can use to open the ImportDatabase dialog. Check with your customizer for details.

At any time while you are setting up a database import, you can view and edit the current SQL query byclicking the View SQL tab on the Import Database dialog box.You can view a plain text version of the importeddata by clicking the Data Preview tab.

Import a database

1. Choose the database to import.

2. Choose the fields to be inserted into the table and set the order of the fields.

3. Set the appearance of the fields and filter the records to be imported.

4. Set the appearance of the fields and filter the records to be imported.

5. Optional: Preview your query by clicking the Data Preview tab on the Import Database dialog box.

6. Optional: Choose the output format (HTML, CALS, or XML) and set up formatting parameters.

Note: You should set output format the first time you import a table into a particular document type.

Choosing a database

Depending the type of database you want to import into your document, the source database might be a file,a folder, or a DSN (Data Source Name).

Microsoft Access databases (*.mdb) and Microsoft Excel spreadsheets (*.xsl) create source databases in asingle file. All other supported database types create source databases in a folder, which may contain severalfiles, each containing a table. Each of these database types contains data in a particular format (for example,Excel) which has not been explicitly associated with a database driver (a program that enables other applica-tions to use the database).

A DSN is a database file that has already been assigned a descriptive name and associated with a databasedriver. A DSN is created using the ODBC utility in the Windows Control Panel.

For any database that has not been converted to a DSN, you must select the appropriate database driver.

XMetaL | Importing databases | 101

Open a database file or folder

1. In the Database area of the Import Database dialog box, click Select.

2. Enable the Driver option and select a driver.


• If you selected the Microsoft Access Driver or the Microsoft Excel Driver, choose the File option• If you selected any other database driver, choose the Folder option

4. In the Source box, type the path and name of the database file or folder.

5. If the database file or folder is password-protected, enter your UserID and password.

Open a Data Source Name

1. In the Database area of the Import Database dialog box, click Select.

2. Enable the DSN option.

3. Select the DSN that you want to import into your document.

4. If the database file or folder is password-protected, enter your UserID and password.

Note: The User ID and Password fields are always enabled if a DSN has been chosen.

Choosing fields and setting their order

Once you have selected a database or DSN, a list of all the fields in the database appears in the AvailableFields list on the Query Builder page of the Import Database dialog box.You now need to create your databasequery by choosing the fields to import, and in what order.

Add fields to a query

1. In the Import Database dialog box, click the Query Builder tab.

2. In the Available Fields list, select a field.

Note: To add more than one field, hold down the Ctrl or Shift key.

3. Click Add.

Note: You can click Add All to add all available fields to the query.

Remove fields from a query


2. In the Available Fields list, select a field.

Note: To remove more than one field, hold down the Ctrl or Shift key.

102 | XMetaL | Importing databases

3. Click Remove.

Note: You can click Remove All to remove all available fields from the query.

Editing a field

Once you have specified which database fields to import, you can specify how (or if) each field is to appear.You can also sort the records according to the entries in specific fields, and set filter conditions to import onlycertain records according to the content of one or more fields.

Edit field properties


2. In the Selected Fields list, select a field and then click Edit.

3. In the Display Name text box, type the name for the field as you want it to appear in your table.

4. In the Show list box, choose an option to show or hide the field in the table.

Note: Hiding a field is not the same as removing it. A hidden field can still be used in a filter condition.

Note: You can cycle through the valid Show and Sort values for a field by double-clicking directly inthe Selected Fields list.

5. Specify a sort order.

Note: Lowercase letters are considered to be lower in order than uppercase letters.

6. Specify a filter condition.

If you selected any option other than None, one or two text boxes appear in which you must type thevalue(s) to match. Text strings must be enclosed within single quotes.

Formatting table and element output

Once you have defined your database query, the fields you are going to show and hide, and the sort order,you must determine the format of the table to be created in XMetaL Author. Tables can be formatted usingthe HTML, CALS, or XML models.

XML table model

The XML model is a sample XML representation of relational data. By default, these tables have the followingstructure:

• The table is surrounded by the <DATA> element.

• Each table row is represented by a <RECORD> element.


• <RECORD> elements contain tags that correspond to the display name (as set in the Query Builder tab) foreach field.

Note: These elements must be declared in your DTD.

You can map the <DATA> and <RECORD> elements to element names in your DTD in the Output Names areaof the page. For example, the following database has two fields, Country and City:

<DATA> <RECORD> <Country>Ecuador</Country> <City>Quito</City> </RECORD> <RECORD> <Country>Bolivia</Country> <City>La Paz</City> </RECORD></DATA>

Output element names

XMetaL Author supports the CALS and HTML table models regardless of the case in which the elements andattributes are declared in your DTD. In the Output Names area of the Output Format page, you can specifythe casing that is correct for your DTD.

In the table of names, the Element/Attribute column displays the generic element and attribute names. TheName to Use column is editable and specifies the forms to be used when the table is written to your document.

Configure the output table

1. In the Import Database dialog box, click the Output Format tab.

2. Choose the table model supported by your DTD.

3. Click Vertical if you want the fields to be imported as columns (as in the original database), or Horizontalif you want the fields imported as rows.

4. Click Show to include the table header (the first row) in the output, or Hide to suppress it.

5. If necessary, specify casing in the Output Names section.

Change an element name

1. In the Name to Use column, select a name.

2. Click Edit and type in the name you want to use.

If your table is in XML format and the <RECORD> and <DATA> elements are not declared in your DTD, it isnecessary to map these elements to elements in your DTD.

Table joins

A join in SQL is a query in which data is retrieved from two or more tables. The two tables must have at leastone field in common. For example, two tables of employee information (a payroll table and an employeeinformation table) could both have an employee ID field. (The field names do not have to be identical, but thetype of data must be the same.)

104 | XMetaL | Importing databases

You can then create a new output record that joins records in the two tables by matching up values in theshared field. For example, you could create records consisting of a salary value from the payroll table and aname from the employee information table.The salary is paired with the correct name because their employeeID values match.

Note: A field does not have to be in the Selected Fields list in order to be used in a join. An unselectedfield can be the field that is matched to the corresponding field in the second table, but that does notappear in the final table.

When you join tables, the fields of the joined table appear in the Available Fields list in the Query Buildersection.You can add add and edit the fields just as you would for a non-joined table.

Ceate a joined table queryXMetaL Author uses SQL.


2. From the Table list box, select a table from the current database. This is the primary table (the table towhich you want to join a second table).

3. Click Table Joins.

4. From the Select Join Field list, choose the field that to use to join the data from the two tables.

This field must contain data common to both tables.

5. Choose the equivalent field from the Join Onto list.

6. Click Add.

Remove a table join


2. Click Table Joins.

3. Select a join.

4. Click Remove.

Update a tableThe database import feature can update an existing table by reloading the data from the source database.

1. Click anywhere inside the table you want to update.

2. Click the toolbar button or menu command that updates the table.


Customizing XMetaL Author

When you first launch XMetaL Author out of the box, there is no default template, only the Standard andFormatting toolbars are visible, and no document is loaded. In this capacity, XMetaL Author functions as ageneral-purpose XML and SGML editor. However, you may find that you need to customize XMetaL Authorfor your DTDs (or schemas) and and user preferences.

The following are some common types of customizations that you can make in XMetaL Author:

• Create and install document templates for each DTD and rules file.

• Record a sequence of keystrokes and actions as a macro. Once you have recorded a macro, you canspecify whether you want it to apply to all documents, or only to documents based on the current DTD.Youcan also specify whether you want the macro to be available to all XMetaL Author users who work from thesame computer.

• Create your own toolbars, toolbar buttons, menus, and menu commands.

• Customize the XMetaL Author environment by setting file, display, and general options.

• Set up Asset Manager files.

For detailed information about customizations, see the XMetaL Customization Guide and XMetaL Programmer’sGuide.

Customizing environments for multiple users

When you work with XMetaL Author on a shared computer, your user options, macros, and toolbar and menuconfiguration are saved to your personal settings folder.Your workspaces are saved to the Windows registry.You can also save cascading style sheet (.css) files for specific DTDs to your personal settings folder. Thenext time you log on and start XMetaL Author, your workspace and personal preferences are automaticallyloaded.

In Windows XP and 2000, the personal settings folder is usually ..\Documents and Set-tings\<username>\Application Data\SoftQuad\XMetaL\5.0.

XMetaL Author looks for the following files in your personal settings folder first. If it cannot find the files, itsearches the XMetaL Author installation folder (usually ..\Program Files\XMetaL 5\Author\) and loadsthe file from there.

• dtdname.tbr (toolbar and menu settings). When you exit XMetaL Author or close all documents based onthe DTD, dtdname.tbr is saved to both the Rules folder (unless the associated .tbr file in that folder is read-only) and to your personal settings folder, even if you have not made any changes to the toolbar and menuconfiguration.

• dtdname.mcr (macros specific to a DTD). If a macro in the dtdname.mcr file in the XMetaL Author folderhas the same name as a macro in this folder, calling the macro name runs the macro in this folder.

• xmetal.mcr (application-wide macros). If a macro in the xmetal.mcr file in the XMetaL Author folder hasthe same name as a macro in this folder, calling the macro name runs the macro in this folder.

• xmetal50.ini (other XMetaL Author settings). Any configurations carried out through the XMetaL Authorinterface (for example, in the Options or Find and Replace dialog boxes) are saved in this file. XMetaL

106 | XMetaL | Customizing XMetaL Author

Author makes changes only to the xmetal50.ini file in your personal settings folder, never to the generalxmetal50.ini file in the XMetaL Author folder.

• dtdname.css (cascading style sheet for a DTD).

• dtdname_structure.css (cascading style sheet for the structure view of a DTD).

• dtdname.ctm (customization file for a DTD). If XMetaL Author has to create .ctm or .css files, it createsthem in the same folder as the related DTD or rules file. If you want to save customization and cascadingstyle sheet files in the personal settings folder, you must move or copy them to the folder. Once XMetaLAuthor finds these files in your personal settings folder, any style or customization changes you make aresaved there.

When you uninstall or update XMetaL Author, your personal settings folder and any macro files and cascadingstyle sheets it contains are not removed. Therefore, you do not have to re-create these files when you re-install XMetaL Author.

Note: xmetal50.ini and any .tbr files are deleted from your personal settings folder when XMetaL Authoris uninstalled.

Creating templates

When you create a file with the New command, you must specify a template. Templates provide documentoutlines, and are also a quick way to create a new document that uses a particular DTD, schema, or rulesfile.

You should create at least one template for each DTD, schema, or rules file.You may be able to create bothan XML and an SGML template for the same DTD, depending on the complexity of the DTD. If the DTD wasdesigned for XML documents, you should be able to create an SGML template for it. However, if the DTDwas designed for SGML documents, it may contain features that are not supported in XML.)

Note: If you select a zero-length file as a template (for example, Blank XML Document template), youmust choose a DTD or Rules file.

Create a template


2. Click the General tab.

3. Select Blank XML Document or Blank SGML Document and click Open.

4. Choose a DTD, schema, or rules file to associate with your template.

5. Add the desired markup and content.

6. Save the file in a subfolder of the Template folder in the XMetaL Author installation folder (usually..\Program Files\XMetaL 5\Author).

Note: Give the file a descriptive name that reflects the template use and associated DTD or schemato make it easier to identify the template.The file extension you assign to your template (.xml or .sgm)determines whether an XML or SGML file is created when the template is opened.

XMetaL | Customizing XMetaL Author | 107

Creating custom toolbars and menus

You can create new toolbars and menus in XMetaL Author, and customize existing ones. Buttons and menucommands can be assigned to built-in commands or user-defined macros.You can create global or DTD-specific configurations: DTD-specific configurations are applied when you edit a document using the associatedDTD. Global configurations apply to all documents.

• To create global toolbar and menu configurations, carry out the customization steps when no document isopen.

• To create configurations for a specific DTD, perform the customizations when a document that uses thatDTD is the active document.

Toolbar and menu customizations are saved in .tbr files that correspond to the name of your DTD or schema.XMetal Author looks for the file in your personal settings folder first. If it does not find the file, it then searchesthe folder specified by the tbr_path variable in the xmetal50.ini file. By default, this variable is set to therules_path value. If it does not find the file in either of these places, it searches the folder that contains theDTD or schema, provided that this is not the Rules folder.

If you are creating a new .tbr file that you want to distribute to other users, you must ensure that they do notalready have a .tbr file for the same DTD or schema in their personal settings folder, because their installationof XMetaL Author will load that .tbr file rather than the one that you have customized for them. If you deletethe .tbr file from their personal settings folder, the next time they open a document based on the associatedDTD, XMetaL Author will load your .tbr file and save it to their personal settings folder.

Note:

• If the DTD or schema is stored in a folder other than the Rules folder, and XMetaL Author finds acorresponding .tbr file in the Rules folder, then the .tbr file in the Rules folder is updated, and no .tbr file iscreated in the folder that contains the DTD or schema.

• Some customized versions of XMetaL Author may not permit changes to the toolbars and menus. Checkwith your customizer for details.

Create a toolbar


2. Optional: Click the check boxes to turn Show Tooltips or Flat Look on or off.

3. Select the Toolbars tab and click New.

4. Type a name and click OK.

A small floating window appears near the top left of the XMetaL Author window. This is your customtoolbar.

5. Click the Buttons tab and select a category.

6. Drag and drop buttons into the new toolbar.

7. Optional: To create a separator line between buttons, click and drag the button to the right.

8. Click Close.


Associate a button with a macroYou can create a new toolbar button, associate it with a macro and an icon image, and add it to a built-in orcustom toolbar.


2. On the Toolbars tab, select the toolbar to which you want to add your button.

3. Click the Button tab.

4. From the Categories list, select Application Macros or dtdname Macros (where dtdname is the nameof the DTD on which the current document is based) .

5. Select a macro.

6. If necessary, click Choose Image to associate the macro with an image or change the associated image.

7. Click the button image for the macro in the Button area, and drag and drop it at the desired location onthe toolbar.

Create a menuYou can create new menus or sub-menus.


2. Click the Menus tab.

3. Click a menu in the tree structure on the left.


• Click Add Menu• Click Add Submenu

5. Type a name for the new (sub)menu in the Caption text box.

Type the & character immediately before the letter that you want to use as the keyboard shortcut (theunderlined letter). For example, “M&ymenu”. The shortcut character you choose must be unique for thatmenu.

6. Optional: If you want to place a separator before this menu, check Begin Group.

7. Optional: Click Move Up or Move Down to position the new menu.

Associate a menu with a macro


2. Click the Menu tab.

3. In the list on the left, click the name of the menu or submenu to which you want to add your macrocommand.

4. Click Add Menu Item.

5. From the Macros list in the Properties area, select the macro that you want to associate with the menucommand.

6. Specify properties as required.

7. Optional: click Move Up and Move Down to position the command.


Setting optionsYou can set the following options through the Tools menu. Settings are saved in the XMetaL configurationfile in your personal settings folder.

Table 4: General options

DescriptionOption

Identifies documents byusername and initials.

Current user

Specifies a location to tem-porarily store remote files.

Location to temporarily store remote files

Displays attributes in atooltip.

Show tag tips

Displays icons in menus.Show icons in menus

Re-opens documents thatwere open when XMetaLAuthor was last closed.

Restore last open documents

Table 5: View options

DescriptionOption

Specifies a default view for openingnew documents.

Open new documents in

Provides formatting information for tagsin Tags On view.

Tag icons

Displays inline images.Show inline images

Displays comments in Tags On view.Show comments

Displays the structure view whenopening a document.

Show structure view by default

Table 6: Plain text view options

DescriptionOption

Specifies a text font.Font

Specifies colors for markup and scripts.Syntax coloring

Determines how tab characters arehandled.

Tab

Specifies how to display lines that arelonger than the width of the documentpane.

Word wrap

Displays line numbers.Line numbering

Table 7: File options

DescriptionOption

Specifies a template for files createdthrough the New Page button.

New


DescriptionOption

Specifies a default extension whensaving new documents.

Save as

Saves backup copies of your files.Backups

Specifies the number of recently useddocuments to display in the File menu.

File menu

Specifies the number of changes orminutes after which your document willbe saved automatically.

Automatic saves

Specifies line ending options for dif-ferent operating systems.

End of line

Table 8: Change tracking

DescriptionOption

Specifies format, color, and preview options for insertedtext.

Inserted text

Specifies format, color, and preview options for deleted text.Deleted text

Setting DITA optionsYou can control some DITA behavior by changing settings in the DITA Options dialog.

To change DITA options on a global basis, that is, for all specializations, close all DITA-based documentsand select Tools ➤ DITA Options.

To change DITA options on a specialization basis, open a specialized document and select Tools ➤ DITAOptions.

Show/hide domains

With the exception of the Typographical domain, domains are groups of elements that are useful in specificindustries such as software development. The Typographic domain includes elements for formatting text,such as Bold and Italic. If you choose to hide a domain, options for inserting elements into the domain willbe disabled or hidden in the user interface. The settings for show/hide domains are specific to the doctypeor specialization.

In the General tab, select a domain from the Hide these domains list and click the button to move it to theShow these domains list.

Auto-assign element IDs

You can control the automatic assignation of element IDs. By leaving the box checked, XMetaL automaticallycreates and assigns globally unique IDs to the elements. If this box is unchecked, the IDs must be manuallyassigned by content authors (by setting each element’s id attribute). The list of element types to auto-assignan ID is specific to the doctype or specialization.

You can also indicate which elements have IDs automatically assigned to them by clicking Options andselecting elements.


When you have set your DITA options to automatically assign element IDs, the following operations can resultin duplicate IDs:

• File ➤ Save As

• Copying files using Windows Explorer or similar mechanisms

• Setting the id attribute through the Attribute Inspector

• Copying/pasting in Plain Text view (in Tags On and Normal views, IDs are adjusted if duplicates exist)

To fix duplicate IDs, clear the id attribute first, then enter a new value or click File ➤ Save to trigger the auto-id generation (if the preference is on).

Note: In general, duplicate IDs are supported by version 1.4 of the DITA Open Toolkit as long as theydo not occur in the same document instance. Problems with duplicate IDs were known to occur in earlierversions of the toolkit.

Note: You can change the format of the generated ID using the DitaSpecializationExtender interface.For more information, see Creating a DITA specialization or the XMetaL Customization Guide.

Allow editing DITA specialization attributes

If you want to change the DITA specialization attributes, then you must first ensure this box is checked.

Update content

Through options in the Update Content tab, you can control the following:

• Downloading of referenced files when opening a repository-based DITA map file

• Behavior when double-clicking a referenced component in a DITA map file

• Refreshing references when opening DITA topics and maps.

Setting a filename prefixBy default, XMetaL Author assigns a prefix to DITA topic filenames when you save a topic for the first time.You can modify this behavior.

File prefixes are specified in ..\XMetaL\Author\DITA\topic_types.xml. Concept, task, and referencetopics are saved with ‘c_’, ‘t_’, and ‘r_’ prefixes. To change this behavior, modify the prefix attribute.

Removing the default prefix

To remove the default prefix from a concept topic, modify topic_types.xml as follows:

<templates_type name="concept"display_name="Concept"template="Concept.xml"prefix=""/>


Keyboard shortcuts

Shortcut keys for XMetaL Author menu commands are indicated on their respective menus. All menus, menuitems, and dialog box controls are accessible by pressing the Alt key and the underlined letter (also calledan access key or mnemonic) associated with that control. XMetaL Author also supports shortcut keys forwindow and dialog box navigation.

In addition to these mnemonic access keys for calling menu commands and dialog box controls, there are avariety of keyboard shortcuts available in XMetaL Author that perform other functions.

Note: If a keyboard shortcut listed in any of these categories does not work in your document, check tosee whether the keystroke combination has been assigned to a macro. If so, that shortcut activates theassigned macro rather than the default function outlined here.

File commands

These shortcut keys give you access to file manipulation commands.

ShortcutAction

Ctrl+NCreate a new document from the default template

Ctrl+TCreate a new document by choosing a template

Ctrl+OOpen a document

Alt+F + number keyOpen a document from the recently-opened list

Ctrl+W OR Ctrl+F4Close a document

Ctrl+SSave a document

Ctrl+QSave all documents

Ctrl+PPrint

Alt+F4Quit XMetaL Author

Ctrl+MPreview document in a browser

F1Display online help

Editing commands

These shortcut keys give you access to common editing operations.

ShortcutAction

Ctrl+FFind and Replace

F3Find Next Forwards

Shift+F3Find Next Backwards

Ctrl+F3Find Selection Forwards

Ctrl+Shift+F3Find Selection Backwards

XMetaL | Keyboard shortcuts | 113

ShortcutAction

Ctrl+Z OR Alt+BackspaceUndo an action

Ctrl+YRedo an action

EscCancel an action

F7Check spelling

Shift+F7Open thesaurus

F9Validate Document

Ctrl+ASelect all

Switching between views and display modes

These shortcut keys switch between XMetaL Author's four editing views, and display invisible table grids.

ShortcutAction

Ctrl + Space barToggle between Normal and Tags On views

Ctrl+Shift+HSwitch to Plain Text view

Ctrl+Shift+OSwitch to Tags On view

Ctrl+Shift+WSwitch to Normal view

Ctrl+Shift+VSwitch to Page Preview

Ctrl+Shift+QHide/show HTML table grid outlines (if no grid selected).

Inserting, deleting, and moving text and markup

These shortcut keys enable you to perform common editing operations on text and markup.

ShortcutAction

BackspaceDelete one character to the left. If you are deleting from thefirst position in a tag, the first character in the tag to the leftis deleted. Any empty tags in between the cursor and thetext to be deleted are deleted as well.

DeleteDelete one character to the right. If you are deleting fromthe last position in a tag, the first character in the tag to theright is deleted. Any empty tags in between the cursor andthe text to be deleted are deleted as well.

Ctrl+X OR Shift+DeleteCut selection (copy to clipboard)

DeleteDelete selection (do not copy to clipboard)

Ctrl+C OR Ctrl+InsertCopy selection

Ctrl+V OR Shift+InsertPaste from clipboard

Ctrl+Shift+EInsert special character

EnterInsert newline in PRE-like element

Shift+EnterTerminate a PRE-like element

114 | XMetaL | Keyboard shortcuts

ShortcutAction

Shift+F6Open or close the Attribute Inspector

F6Open and place active cursor in the Attribute Inspector

Enter OR Ctrl+Shift+PSplit element (where allowed by the DTD)

Backspace (at beginning ofelement) OR Ctrl+Shift+J

Join to preceding element (where allowed by the DTD)

Delete (at end of element)Join to following element (where allowed by the DTD)

Ctrl+Shift+DRemove markup

Ctrl+Shift+LOpen or switch Element List to “Change element” mode

Ctrl+Shift+TSelect element

Ctrl+Shift+IOpen or switch Element List to “Insert element” mode

Ctrl+Shift+EnterInsert selected element from floating Element List dialogbox, and dismiss dialog box

F8Insert a comment

List formatting

These shortcut keys perform list formatting.

ShortcutAction

TabDemote selected list items to sub-list

Shift+TabPromote selected list items out of list

Moving around in a document

These shortcuts move the insertion point in the XMetaL Author document pane. See the next section forshortcuts for moving around in tables.

ShortcutAction

F4Scroll to insertion point or selection

Left arrowOne character to the left

Right arrowOne character to the right

Ctrl + Left arrowOne word to the left

Ctrl + Right arrowOne word to the right

Up arrowUp one line

Down arrowDown one line

EndTo the end of a line

HomeTo the beginning of a line

Page UpUp one screen (scrolling)

Page DownDown one screen (scrolling)


ShortcutAction

Ctrl+EndTo the end of a document

Ctrl+HomeTo the beginning of a document

Moving around in tables

These shortcuts move the insertion point in tables. See the previous section for shortcuts for moving aroundin the rest of the document pane.

ShortcutAction

Tab OR Right arrowNext cell in a row

Shift+Tab OR Left arrowPrevious cell in a row

Alt+HomeFirst cell in a row

Alt+EndLast cell in a row

Alt+Page UpFirst cell in a column

Alt+Page DownLast cell in a column

Up arrowPrevious row

Down arrowNext row

Click to right of the tableOutside the table

Making and extending selections in a document

These shortcut keys enable you to make or extend selections (highlighted text or markup).

ShortcutAction

Shift + Right arrowOne character to the right

Shift + Left arrowOne character to the left

Ctrl+Shift + Right arrowTo the end of a word

Ctrl+Shift + Left arrowTo the beginning of a word

Shift+EndTo the end of a line

Shift+HomeTo the beginning of a line

Shift + Down arrowOne line down

Shift + Up arrowOne line up

Ctrl+Shift+HomeTo the beginning of a document

Ctrl+Shift+TSelect the current element

Ctrl+ASelect the entire document

TabSelect the contents of the next cell in the table

Shift+TabSelect the contents of the preceding cell in the table


Making and extending cell selections in a table

These shortcut keys enable you to make or extend selections of a block of cells within a table.

ShortcutAction

Shift + Right arrowExtend selected cell block by one cell to the right

Shift + Left arrowExtend selected cell block by one cell to the left

Shift + Down arrowExtend selected cell block by one cell down

Shift + Up arrowExtend selected cell block by one cell up

Choosing menu commands

These shortcuts enable you to choose commands from the XMetaL Author menus.

ShortcutAction

Shift+F10Show the shortcut (right mouse) menu

Alt + Space barShow the program icon menu (on the program title bar)

Down arrow, Up arrowSelect the next or previous command on the displayed menuor sub-menu

Left arrow, Right arrowSelect the menu to the left or right; or, with a sub-menuvisible, switch between the main menu and the sub-menu

AltClose the visible menu and sub-menu at the same time

EscClose the visible menu; or, with a sub-menu visible, closethe sub-menu only

Moving between panes, documents, and dialog boxes

These shortcuts enable you to move between panes, dialog boxes, and documents.

ShortcutAction

Alt+TabSwitch to the next active program.

Alt+Shift+TabSwitch to the previous active program.

Alt + Right arrow OR Ctrl+F6 OR Ctrl+TabMove the active cursor to the next document.

Alt + Left arrow OR Ctrl+Shift+F6 ORCtrl+Shift+Tab

Move the active cursor to the previous document.

Ctrl+EscShow the Windows Start menu.

Ctrl+WClose the active document pane

Alt+F6Toggle between the active document and the most recently active modelessdialog box. If no modeless dialog boxes are open, the shortcut has noeffect.

Alt+Shift+F6Cycle through the active document and any open modeless dialog boxes.If no modeless dialog boxes are open, the shortcut has no effect.


Navigating in a dialog box

These shortcut keys enable you to select and use dialog box controls (controls are groups of one or morerelated objects, such as a push button, or a group of radio buttons).

ShortcutAction

Ctrl+Tab OR Ctrl+Page DownSwitch to the next tab in a tabbed dialog box

Ctrl+Shift+Tab OR Ctrl+Page UpSwitch to the previous tab in a tabbed dialog box

TabMove to the next control

Shift+TabMove to the previous control

Alt + underlined letterMove to control

Arrow keysMove between options in the selected drop-down list box

Arrow keysMove between radio buttons in selected group

Space bar OR EnterPerform the action assigned to the selected button

Space barTurn selected check box on or off

Alt + underlined letterTurn any check box on or off

First letter in option nameMove to an option a selected drop-down list box

Alt + Down arrowOpen selected drop-down list box

EscClose selected drop-down list box

EnterPerform the action assigned to the default button in the dialog box (if noother push button is selected)

Arrow keysSelect a folder in a folder list

F5Update the files visible in the Open or Save As dialog box

EscCancel the command and close the dialog box


Introduction to DITA

DITA stands for ‘Darwin Information Typing Architecture’. It is an architecture for creating and maintaininginformation in print and online.

Using DITA, you can deliver content to multiple channels. DITA architecture is extensible, which means thatyou can modify its structure to enable the reuse and repurposing of content across an entire organization:technical publications, marketing whitepapers, user guides, sales collateral, internal communications, onlinehelp systems, web sites, quick reference, and more.

Content that is authored using the DITA architecture is easily reused and repurposed because of its highdegree of granularity, that is, the small size of each piece of information. The underlying paradigm for DITAis that content is encapsulated in topic-sized chunks.

Authoring content using DITA is a familiar process for authors, because all document components are availablein the XMetaL interface.

TopicsTopics are units of information that are meaningful when they stand alone. In DITA, topics are structured bytopic type.

Topic types

DITA has the following basic topics types:

• Task

• Concept

• Reference

• Topic (generic)

Each type has a DTD. This means that a topic can contain only specific elements in a specific order. Forexample, only task topics can contain step results (created by the stepresult element), and a step resultcan appear only as part of a step.

This architecture creates a standard structure for information that you can use to easily create consistentlyorganized content. However, before you begin authoring, you need to identify the purpose of the informationin order to create the correct content type.

Many teams adopt XML and DITA because they want to reuse content rather than rewriting the same contentslightly differently for each deliverable. For example, you may need an online Help system that contains mostof the information that is in a user guide in PDF format. Instead of having to write, edit, review, publish, andtranslate that information again, you can use the same topics in both deliverables. The key to successfullyimplementing this strategy is topic-based authoring.

Topic-based authoring

Topic-based authoring is the process of creating information in topics. The biggest hurdle to overcome whenstarting to author topics is to change your mindset from writing a deliverable, such as book or chapter, towriting a topic. This may be a challenge for authors who are used to writing in an unstructured environment

XMetaL | Introduction to DITA | 119

in which they simply type the content without considering its purpose. In topic-based authoring, you firstidentify the purpose of the information, pick the appropriate topic type, and only then do you start writing thecontent.

Another challenge is remembering that a topic could appear anywhere, in any deliverable. Because a topicis designed to be a self-contained unit of information, you must be careful not to include contextual informationthat limits the topic for use in only a specific deliverable. For example, when writing a chapter, you might havewritten

For more information, see the following section about databases.

When you write the same content in a topic-based method, you would write

For more information, see Databases.

In this case, ‘Databases’ is a link to the next section. The key difference is that the second example does notinclude the context-specific information about where the database information is located.

Topic structureAlthought DITA topic structure varies by topic type, all DITA topics share some basic elements.

Topic title

The topic title is the equivalent to a level 1 header and provides the main identifying test for the topic. DITAalso supports alternative titles for display as navigation titles and in search results.You may need to specifya navigation title when the topic title is long and you want a shorter title to appear in the table of contents.You can specify a search titles when you want to provide additional clarification in the title that appears insearch results, but not in the topic itself.

Short description

The short description is the first paragraph that appears directly after the title and before the body of the topic.The short description serves the following purposes:

• Introduce the subject matter covered in the topic when the reader opens the topic

• Provide a summary of the topic contents when the reader sees it listed as part of the automatically-generatedlinks in HTML output

Although the short description is not a required element, it is recommended that you include it.

Prolog

You can specify the metadata that applies to the entire topic in the prolog. This includes index entries andkeywords that apply to the entire topic, as well as author and copyright data.

Topic body

The topic body contains the topic content. Each topic type has a unique body structure.You must includesome standard information in each type. Concept and reference topics have the most flexibility in what elementsyou can include and where. For example, concept topics usually include sections, paragraphs, bulleted lists,and images. Reference topics usually contain tables.

120 | XMetaL | Introduction to DITA

By contrast, the task topic type is restrictive because it allows only one set of steps and prescribes an orderin which you can use the elements. For example, you cannot have a result element before the steps. Thishelps you author information more easily and is intended to follow the logical flow of information.

MapsMaps are XML files that organize DITA topics for output.

Maps organize topics into a hierarchy that becomes the table of contents in the deliverable you generate.They also serve as the manifest file for the project. If you want content to appear in the output, you must listinclude a topicref element in the map that identifies the topic.You can control whether the topic is listed inthe TOC by setting attributes in the map.

Content re-use

DITA maps are one of the primary drivers of content re-use. They support re-use by allowing you to includethe same source content in multiple deliverables. For example, you can create a map file that organizes thetopics for an online Help system.You can then create another map file that uses many of the same topicsas well as additional topics to generate a PDF file. Because you can use the same topics and do not haveto copy and paste content for each deliverable, you can save time and effort.

In addition, you can nest maps within maps. This allows you to create maps that group and organize a setof topics that you want to use together. Instead of having to create a single map and add all the topics, youcan create a master map and add references to each of the other maps. This allows you to easily includegroups of topics that belong together in multiple deliverables.

Links

Maps also control how links between topics are generated. By default, when you generate HTML or helpformats, the DITA Open Toolkit generates links between parent topics and the child topics that they containin the map.You can control whether these links are uni-directional or bi-directional using attributes in themap.

To create non-hierarchical links or links between peer topics, you control the link generation in the map witha relationship table. The table is based on the topic types, with a column for each type.

Relationship tablesRelationship tables are a special type of table where the columns define the topic type and the rows definethe relationship between the topics.

Structure

Relationship tables organize <topicref> elements by topic type to generate links between the topics. Thecolumns define the topic type and the rows define the relationships between topics.

You can control the direction of the links for each row in the table. This means that you can links that are uni-directional or that only appear in one topic in a row and not in the others.

XMetaL | Introduction to DITA | 121

Benefits

One key benefit of using a relationship table to generate links between topics rather than specifying the linksin each topic file is that you can easily find and maintain all the links between topics because they are storedin one file, the map file. If the file name changes for a topic, you open the map file and update all the referencesto the file in a single location; you do not have to edit each file that links to the topic. This is especially usefulwhen you are troubleshooting links when generating a deliverable.

DITA referencesYou can access DITA reference information and sample files through the Help menu.

Table 9: Supporting documentation

DescriptionPublication

Covers basic information about creating DITA topics andmaps as well as background information about structuredauthoring and the advantages of using DITA.

XMetaL Evaluation Guide

Describes the purpose of each DITA element and the rulesassociated with it.

DITA Language Reference

The OASIS DITA specification. Describes DITA markup,processing, and specialization. Also provides backgroundinformation on terminology and the DITA DTD/schema.

DITA Architectural Specification

Describes the Java-based implementation of the OASISDITA specification, including processing targets such asHTML and PDF.

DITA Open Toolkit User Guide

122 | XMetaL | Introduction to DITA

Authoring DITA content

Authoring content using DITA is a familiar process for authors, because all document components are availablein the XMetaL interface.You can edit components and get help on current elements through the menus.

You can view information about the current element by clicking Help ➤ Help on Current Element. Elementsand attributes are described in the DITA Language Reference. The reference also includes usage examples.

Sample DITA documents are available by clicking Help ➤ DITA Sample Files.

Create a topicYou can create a new topic using the standard XMetaL file creation steps.


2. Click the DITA Topic tab.

3. Choose one of the following templates:

• Generic Topic. Topic with no specific or defined type.• Concept. Topic to contain conceptual information.• Reference. Reference material.• Task. Task-based (usage or workflow) information.• Composite. Lets you create a compound document, consisting of multiple topics.

Insert a sectionSections let you organize the information within a topic. Sections cannot be used to represent a hierarchywithin a topic; they cannot be nested. Sections are specific to the topic type.

1. Click Insert ➤ Section.

2. Choose from the following section types:

• Generic section. A generic division of information.• Example. Illustrates a concept.• Task Prerequisites,Task Context,Task Result,Task Postrequisites. Describes task components.• Reference Syntax. Describes syntax for properties in reference topics.

Insert a subtopicYou can add a new subtopic to the topic you are currently working in. New subtopics are inserted nestedinside the currently-selected topic.

1. Click Insert ➤ Subtopic.

2. Choose from the following topic types:

• Task. Task-based (usage or workflow) information.• Concept. Topic to contain conceptual information.

XMetaL | Authoring DITA content | 123

• Reference. Reference material.• General Topic. A single-subject topic or article.

Note: The type of topic you can insert depends on the type of topic you are working in.

Insert a paragraphThe paragraph is a basic block element.You can insert a normal paragraph, a note, or a quotation.

1. Click Insert ➤ Paragraph and select one of the following:

• Normal paragraph• Note• Quotation

Tip: You can change the type of note, for example, to a warning or a tip, by clicking Paragraph ➤Change note type.

Insert an elementYou can insert elements through the the Insert menu or through the Element List (View ➤ Element List).

When you use the Insert menu, the Smart Insert feature prevents you from inserting an element at an invalidlocation. If the element you select is not valid at the current location, it is inserted at the next valid location inthe document. Smart Insert behavior also includes the following:

• Pasting.You cannot paste elements or text at an invalid location.They are inserted at the next valid locationin the document.

• Typing.You cannot type text at an invalid location in the document.

• Deleting.You cannot delete an element if it is required at a particular location.

1. Position the cursor where you want to insert an element.

2. Click Insert and select an element type.

Insert an inline elementYou can insert elements which are inline, or, in other words, are not preceded or followed by a line break.You can think of inline elements as corresponding to character-level markup. Inline elements are frequentlyused to apply text formatting changes, such as bold and italic. They can also be used to specify position,such as superscript and subscript.

1. Click Insert ➤ Inline Element.

2. Select the element type you want to insert.

124 | XMetaL | Authoring DITA content

Insert a multimedia objectYou can insert multimedia objects in your DITA topic.

1. Click Insert ➤ Object.

2. Choose the object you wish to insert.

Insert a list of stepsYou can insert a list of steps in a Task topic.

1. Position the cursor at the location where you want to insert a list of steps.


• Click Insert ➤ Steps ➤ Steps List.• Click Insert ➤ Steps ➤ Unordered Task Steps.

XMetaL inserts a list of steps containing one task step component.

Insert a step componentTask steps include additional components such as choices and examples.

1. Position the cursor at the location in the step where you want to insert a component.

You may find working in Tags On view is preferable for this.

2. Click Insert ➤ Steps and choose a component.

Creating cross-references and related linksCross-references and related links provide a way to direct readers to additional information. This informationcan exist in another DITA topic, a non-DITA file, or a Web page.

Cross-references link to a different location within the current topic, or a different topic within the same helpsystem, or to external sources, such as Web pages, or to a location in another topic.

Related links define a relationship to another topic.

Cross-references can be inserted in most places within a topic. Related links can be inserted only at the endof topics.

You can insert a link by clicking Insert ➤ Link and choosing a link type.

Table 10: Link types

Default valueAttributeElementDescriptionName

the target elementhref<xref>Specify a location within thecurrent topic, another DITA

Cross-reference

the type of the target element, e.g.,fig, table

typetopic, or a location withinanother DITA topic


Default valueAttributeElementDescriptionName

ditaformat

localscope

the target elementhref<xref>Specify a file on your filesystem or content repository

File reference

file extension of the target file, e.g.,pdf

format

peerscope

the target elementhref<xref>Specify a URL or e-mailaddress

Web link

htmlformat

externalscope

the target elementhref<link>Specify a DITA topicRelated link to topic

the type of the target element, e.g.,fig, table

type

ditaformat

localscope

the target elementhref<link>Specify a Web page or e-mail address

Related link to Webpage

htmlformat

externalscope

the target elementhref<link>Specify a file on your filesystem or content repository

Related link to File

file extension of the target file, e.g.,pdf

format

peerscope

Insert a cross-referenceWhen you insert a cross-reference, XMetaL inserts an <xref> element.

1. Click Insert ➤ Link and select one of the following:

• Cross-Reference to specify a location within the current topic, another DITA topic, or a location withinanother DITA topic

• File Reference to specify a file on your file system or content repository• Web Link to specify a URL or e-mail address

If you select Cross-Reference, XMetaL also inserts the title of the topic you selected.This text is refreshedwhen you refresh references or when you generate output.

2. Depending on your selection, do the following:

• Click Browse and select a file• Select a target element type• Type a URL

Insert a related linkWhen you insert a related link, XMetaL inserts a <link> element.

1. Click Insert ➤ Link and select one of the following:

• Related Link to Topic to specify a DITA topic


• Related Link to Web Page to specify a Web page or e-mail address• Related Link to File to specify a file on your file system or content repository

If you select Related Link to Topic, XMetaL also inserts the title of the topic you selected. This text isrefreshed when you refresh references or when you generate output.

2. Depending on your selection, do the following:

• Click Browse and select a file• Select a topic title• Type a URL

Refresh referencesReferences that you have already inserted into your DITA topic or map file may not remain up to date,especially if you are modifying topic names. It may therefore be necessary to refresh these references.


• Open a DITA topic file and click Edit ➤ Refresh All References.• Open a DITA map file. In the map editor, click Edit ➤ Refresh All References.

Insert topic metadataYou can change view and edit elements in the topic prolog using the Topic Metadata dialog. The Normaland Tags On views show the content that would normally appear in output. Metadata is handled through thisdialog.The dialog contains most, but not all topic <prolog> elements.Your organization may decide to choosewhich metadata elements are important to it, and subsequently customize this dialog for more efficientworkflow.Your organization can also replace text fields with dropdown lists, checkboxes, and radio buttons.If you want to modify or streamline your Topic Metadata dialog, contact JustSystems support for informationon how to do this customization.

1. Click Insert ➤ Topic Metadata.

2. Select the metadata item you want to change or add values to from the list on the left side of the dialog.The fields in the middle of the dialog change, depending on what metadata item you selected.

3. Indicate the value(s) you want the selected metadata item to have.

Promote or demote a topicYou can promote or demote a topic within a generic topic, or a topic-like element (such as a concept or task)in a composite topic.


• In a generic topic, select a topic• In a composite topic, select a topic or topic-like element

2. Do one of the following

• Click Edit ➤ Promote Topic• Click Edit ➤ Demote Topic


The topic is moved one level up (or down) in the topic hierarchy.

Editing propertiesYou can edit most elements through the Edit Properties dialog.

Some of these editing dialogs also let you apply conditions.

Do thisTo edit

Select or place the cursor in the element you wish to edit and click Edit ➤ Element PropertiesElements

Click Insert ➤ Topic MetadataTopic metadata

Place the cursor in the table you wish to edit and click Table ➤ Table PropertiesTables

Select or place the cursor in the index entry you wish to edit and click Edit ➤ Element

Properties

Index markers

Creating indexesYou can create full-featured indexes for your documents by adding index markers to your topics.

Index markers can contain the following:

• Simple terms consisting of one or more words

• Terms that indicate a parent-child relationship, or sub-entries

Options

You have the option of specifying alternate sorting for a term. For example, you may want to sort the terms‘E*Carrall’, ‘E*Kennel’ , and ‘E*Terrarium’ as ‘ECarrall’, ‘EKennel’, and ‘ETerrarium’.You can also add termsthat refer to other terms. These are called ‘See’ or ‘See also’ terms.

To specify that your index term is covered in a range of pages, you need to create page range index markers.For example, you may have a topic, ‘Mammals’, that is discussed from pages 3 to 4. In this case, need toinsert one index marker at the beginning of the discussion to indicate the start of the range, and one at theend to indicate the end of the range.The current page is the default range. In this case, no range is specified.Page ranges are identified by name.

Table 11: Index marker options

To do thisUse this option

Specify alternate sorting for the termSort as

Create an index term that refers to another index termRefer to another index term

Specify a page range for the current index termPage range


A complex index

The following printed index illustrates the scope and complexity of the indexing optionsavailable. Here you see simple terms, parent-child terms, alternate sorting, ‘See’ and ‘Seealso’ terms, and page ranges. Creating page ranges requires two index markers. Theindex term is left blank for the end of page range marker.

Some of the terms beginning with ‘E’ specify alternate sorting. Under default sorting rules,the terms beginning with ‘E*’ would appear first. However, these markers specify analternate sorting.Therefore, ‘Endopterygota’ and ‘Entomology’ appear between ‘E*Kennel’and ‘E*Terrarium’.

Insert an index markerYou can add index terms to your topics by inserting index markers.

1. Click Insert ➤ Index Marker.

2. Type the index term in the Index entry field.

You can create sub-entries by separating terms with commas.

Tip: In your document, select the word you wish to use as an index term. The word appears in theIndex entry field.

3. Specify options as required.


• In the Sort as field, specify an alternate sorting for the term. Type how you want the term to be sorted.• From the Refer to another index term dropdown, select See or See also. Type the term to which you

want to refer.• Specify a page range and name the range. Select Start of page range for the first page in the range

and End of page range for the end of the range.

Note: If you are inserting an end of page range marker, leave the index term blank.

Tip: You can add additional markers by clicking the More Markers button.


Re-using content

You can re-use content within and among documents using the conref attribute. This feature is useful forboilerplate text and names that may change frequently such as product names or version numbers.

The conref attribute allows you to refer to another element and use that element’s content in place of thecurrent element.You can insert reusable content into your document in the following ways:

• By inserting a reusable component. You insert a reference to an element that you have previously createdand saved as a reusable component. If you insert as linked content, the element specifies a conref attributeand includes any child elements that are necessary for the document to be valid.You can refresh the ref-erence at a later time. If you insert a copy, the element and its content is copied into the document just asif you had typed it.

• By attaching a content reference to an element. You can add a conref attribute to an exising element.The target must have an ID specified.

• By inserting an element with a content reference. You can create an element that specifies a conrefattribute and any child elements that are necessary in order for the document to be valid.

XMetaL distinguishes between referenced content and local content. Referenced content is stored outsideof the current element, either within the same file or in another file. Referenced content is specified by theconref attribute. Local content (referred to as ‘placeholder’ in the DITA Architectural Specification) consistsof a parent element and any child elements necessary to maintain validity in the source document. It includesthe text, attributes, and other elements that you create during the authoring process and is stored within theparent element.

In Normal or Tags On view you can choose to display the local content or the referenced content. When yougenerate output, local content is replaced with referenced content.

Example

The following file contains a section (‘Canines’) that specifies local content and referencedcontent from another file.



<concept id="animals"> <title>Animals</title> <conbody> <section> <title>Felines</title> <p>Here is everything you need to know about cats.</p> </section> <section conref="animals_for_children.dita#animals_for_children/doggies">  <title>Canines</title> <p>Here is everything you need to know about dogs.</p> </section> ...



<concept id="animals_for_children"> <title>Animals for children</title> <conbody> <section id="doggies">

XMetaL | Re-using content | 131

<title>Doggies</title> <p>Doggies are cute and playful.</p> </section> ...

Displaying reusable contentWhen you open a file, referenced content is displayed according to the refresh content preferences you haveset in your DITA options.

If you have your DITA options set to refresh references when opening a topic or map, referenced content isdisplayed.

If you do not have your DITA option set to refresh references, click Edit ➤ Refresh All References to refreshand display all referenced content.

You can show or hide individual reusable components or content references by clicking Reuse ➤ ShowLocal Content or Reuse ➤ Show Referenced Content.

When you show referenced content, it appears in a gray background. It is not editable.

When you show local content, if the element does not have content, its mini-template is displayed. The mini-template contains a parent element and any child elements that are necessary for the document to be validas well as prompt text.You can edit the mini-template text to replace it with your own content.

Figure 1: Document with referenced content showing

Figure 2: Document with local content (and mini-template) showing

Validating referenced content

When you validate a document, referenced content is not checked for validity. Referenced content is checkedfor validity when you refresh references. If there is invalid local content and you jump to the validation error,the local content is displayed.

When a content reference is created, or the refresh process is run on a content reference, the reference ischecked to ensure that it is valid in the current context.

Content references must conform to the following requirements:

• The target file specified must exist

132 | XMetaL | Re-using content

• The target ID in the target file must exist

• The target document must be valid XML

• The target must be a different node than the source node, i.e., it must not be a circular reference

• The target element and the source element must be of the same type or the target element must be gener-alizable back to the source type

• The target domain set must be equal to or a subset of the source domain set

• The target element must be a descendent of a topic or a map

Operations that select content

Find and replace, spell check, and track changes accept/reject functions operate on local content only.Theseoperations may force local content to be displayed.

Refreshing reusable content

You can set DITA options to refresh references when opening a topic or map.

If you do not have your DITA option set to refresh references, you can refresh all reusable components andcontent references by clicking Edit ➤ Refresh All References. When you refresh references, the latestversion of all referenced content is displayed. Local content is not overwritten.

You can refresh individual reusable components or content references by clicking Reuse ➤ Refresh andShow Referenced Content.

Editing referenced content

You can edit the target of any conref attribute by clicking Reuse ➤ Open Referenced File.

Removing a content reference

To remove a content reference, click in the element that contains the reference and click Reuse ➤ DetachContent Reference. This removes the conref attribute from the parent element and the referenced contentcan no longer be displayed.

Generalizing elements with content referencesUsing the Insert Element with Content Reference or Insert Reusable Component commands, when youattempt to insert a specialized element that is not in the current content model, XMetal inserts a generalizedelement that is valid in the current context.

For example, if you attempt to insert a <steps> element with a conref attribute in a Reference topic, XMetaLinserts an <ol> (ordered list) element. This is because <ol> is the parent class of <steps> and it is validwithin a Reference topic, whereas <steps> is not. The original (specialized) element names are visible whenreferenced content is displayed. This behavior is consistent with rules for generalizing content references asspecified in the DITA Architectural Specification and the DITA Open Toolkit User Guide.

Create a reusable componentWhen you create a reusable component, you save the selected element(s) in a separate file.


1. Select the content you want to make into the reusable component.

Note: A reusable component refers to a single target element. If you want to reference multipleelements, they must be contained within a single parent element. Therefore, if you need to referenceseveral block elements that do not have a common parent, you will need to create multiple reusablecomponents.

2. Click Reuse ➤ Create Reusable Component.

3. Enter the following information:

• Component range. Select the current element or an ancestor.• Description. Type a description for the component.• If you want to replace the selected text with a reference to the component you are in the process of

creating, click Replace selected content with a reference to the new component. When you selectthis option, XMetaL creates a conref attribute on the current element and assigns a value to it. Thevalue contains the ID of the reusable component. The contents of the current element are replaced withthe element’s mini-template.

4. Click Continue and save the component.

Insert a reusable componentYou can insert an element you have saved as a reusable component either as linked content or as a copy.

1. Place your cursor where you want to insert a reusable component.

2. Click Reuse ➤ Insert Reusable Component.

3. Select a file.

4. Choose one of the following from the Insert As list:

• Linked content. The element is inserted as a reference using a conref attribute. A mini-template isalso inserted as local content. Because the referenced content is not stored locally, the most recentversion is always shown whenever the reference is refreshed.

• Copy. The element is copied into the document just as if you had typed it. A conref attribute is notcreated. Because the content is stored locally, the copied content will not change when the originalcontent is modified.

Insert an element with a content referenceYou can insert an element with a conref attribute from a single dialog.

1. Place your cursor where you want to insert an element with a content reference.

2. Click Reuse ➤ Insert Element with Content Reference and select the file that contains the element youwant to reference.

3. Choose an element.

You can preview the content in Page Preview (styled) or Plain Text view before you insert it.

134 | XMetaL | Re-using content

Attach a content reference to an elementYou can specify a conref attribute on an element you have already created through menu commands orthrough the Attribute Inspector.

1. Place your cursor inside the element to which you want to attach a content reference.

2. Click Reuse ➤ Attach Content Reference.

3. If the local element specified is not the one you want, select an element from the dropdown list.

4. Select the file that contains the element you want to reference.

5. Choose an element.

You can preview the content in Page Preview (styled) or Plain Text view before you insert it.

Tip: You can detach a content reference by clicking Reuse ➤ Detach Content Reference.


Working with DITA maps

You can organize your DITA topics in a DITA map. XMetaL provides a Map Editor.

Each open map has its own tab in the Map Editor.You can control the order and hierarchy of the topics inthe map by selecting them and clicking the arrow buttons to move them around in the map layout.

You can create topics at the time they are added to the map, or insert previously-created topics.When insertingtopics into your map, you may want to organize them into groups of related topics. Topic headings serve ascontainers for those groups of related topics.

If you have previously created a DITA map, you can insert it into a new map, making the previously-createdmap a part of the new map.

You may find that as you edit topics, the references in references your map become out of date. In this case,you can update all references in your map file at one time.

Editing DITA maps

XMetaL provides the following options for editing DITA map files:

• The map editor, which includes map-specific menus.

• The XML view of the map, which displays the map in the document window.

In XML view, you can do the following:

• Create and edit relationship tables

• Perform multiple-selection operations

• Copy and paste and drag and drop selections

• Edit map XML markup in Plain Text view

• Create and insert conrefs

• Create and edit metadata

Note: When you try to open an invalid map, the map will not appear in the map editor. However, if youswitch to XML view, you can view the map and fix validity problems.

Create a mapYou can create a new map using the standard XMetaL file creation steps.


2. Click the DITA Map tab, choose the DITA map template and click OK.

3. Type a title for the map.

Note: The map title is saved in the <title> element.

136 | XMetaL | Working with DITA maps

Create and insert a topicYou can create DITA topics at the time they are added to the map.

1. In the Map Editor, click Insert ➤ Topic Reference.

2. Enter a topic title. This is the text that appears as the title of the newly created topic.

3. Click Create.

4. Select a DITA Topic or DITA Map template and click OK.

5. Type a name for the topic file and click Save.

Insert an existing topic

1. In the Map Editor, click Insert ➤ Topic Reference.

2. Choose the topic file and click Open.

If you choose a composite DITA topic, you can refer to all the topics in the file, or you can select one topic.

Insert a topic group

1. In the XML view of the bookmap, place your cursor where you want to insert a topic group.


• Click Insert ➤ Topic Group.• Double-click topicgroup in the Insert Element list.

3. Click Insert ➤ Topic Reference to add a topic to the group.

Insert a reference to a non-DITA file

1. In the Map Editor, click Insert ➤ File Reference.

2. Click Browse and select a file.

3. Type a navigation title.

Insert a Web linkYou can insert references to Web pages into the map.

1. In the Map Editor, click Insert ➤ Web Link.

2. Type a URL.

3. Type a navigation title.

XMetaL | Working with DITA maps | 137

Insert a map referenceIf you have previously created a DITA map, you can insert it into a new map, making it a part of the new map.

1. In the Map Editor, click Insert ➤ Map Reference.

2. Click Browse and select a map file.

3. Type a map title.

Insert an Eclipse navigation referenceNavigation references are supported for Eclipse output only.

1. Open a DITA map.

2. In the Map Editor, click Insert ➤ Eclipse Navigation Reference.

3. Click Browse and select a file.

Insert a topic headingWhen inserting topics into your map, you may want to organize them into groups of related topics. Topicheadings serve as containers for those groups of related topics.You can create these headings at any timeand later use the arrow keys to move topics into the order that you want.

1. In the Map Editor, click Insert ➤ Topic Heading.

2. Type the topic heading as it will appear in the map.

Insert a relationship table

1. Open a DITA map.

2. In the Map Editor, click File ➤ Switch to XML View of Map.

3. Position your cursor where you wish to insert the relationship table and click Table ➤ Insert RelationshipTable.

4. Type a title for the table and select columns.

Edit a map in the Map Editor

1. Open a DITA map and select an item.

2. In the Map Editor, click Properties.

Note: The Map title property in the Map Properties dialog displays the contents of the <title>element. If the <title> element does not exist, the contents of the title attribute are displayed.

138 | XMetaL | Working with DITA maps

Edit a map in XML view

1. Open a DITA map file.

2. In the Map Editor, click File ➤ Switch to XML View of Map.

Tip: You can switch back to the Map Editor by clicking File ➤ Switch to Map Editor through theeditor menus.

XMetaL | Working with DITA maps | 139

Working with DITA bookmaps

DITA bookmaps let you organize book-type components and metadata.

Basic book-level components include chapters, appendixes, and parts. However, bookmaps also provides acomprehensive set of front and back matter to let you create special topics, for example, abstracts, notices,and prefaces.You can also specify booklists such as tables of contents, glossaries, and indexes.

You create and insert bookmap components in XML view using the Insert menu or Element List.

You can view the bookmap through the Map Editor.

You can specify additional information about your bookmap with metadata.You add bookmap metadatathrough the Element List.

In addition to bookmap-specific components, you can also insert DITA map components such as topics, topicheadings, and topic groups into your bookmap.

Generated components

Some components act as placeholders and are generated when you create output.This is generally the casefor booklists such as indexes, tables of contents, and lists of figures and tables. Generated components are

denoted by the symbol in the Map Editor.You do not need to provide a topic for these files.

Create a bookmapYou can create a bookmap using the standard XMetaL file creation steps. XMetaL displays the bookmap inXML view in the document window. The tabbed interface lets you navigate between open bookmaps.


2. Click the DITA Map tab and choose the DITA bookmap template.

Insert bookmap metadataYou can add bookmap metadata through the Element List. Metadata is grouped within a bookmeta element.

1. In the XML view of the bookmap, place your cursor where you want to insert metadata.

2. In the Element List, double-click on bookmeta.

3. Add metadata elements to the bookmeta element using the Element List.

Insert an existing component

1. In the XML view of the bookmap, place your cursor where you want to insert a bookmap component.

2. Click Insert and select a component type.

3. Click Browse and select the component file.

140 | XMetaL | Working with DITA bookmaps

Open a component

1. In the XML view of the bookmap, place your cursor in the component you want to open.

2. Click Reuse ➤ Open Referenced File.

Create and insert a chapter, appendix, or part

1. In the XML view of the bookmap, place your cursor where you want to insert a chapter, appendix, or part.

2. Click Insert and select Chapter Reference, Appendix Reference, or Part Reference.

3. Type a title, click Create, and select a DITA Topic or Map template.

4. Select a DITA Topic or DITA Map template.

5. Type a name for the file and save.

Insert front or back matter

1. In the XML view of the bookmap, place your cursor where you want to insert front or back matter.

2. Click Insert and select Front Matter Section or Back Matter Section.

3. Insert components as required.

Create and insert a special topic

1. In the XML view of the bookmap, place your cursor where you want to insert a special topic.

2. Click Insert and select Abstract, Draft Introduction, Notices, Dedication, Colophon, or Preface.

3. Type a title, click Create, and select a DITA Topic or DITA Map template.

4. Type a name for the file and save.

Create and insert a booklistBook lists contain reference and navigational information. Some lists are generated when you create output.

1. In the XML view of the bookmap, place your cursor where you want to insert a booklist.

2. In the Insert Element list, double-click the booklists element.

3. With your cursor positioned within the booklists element, click Table of Contents and select FiguresList, Tables List, Abbreviations List, Trademark List, Bibliography, Glossary, or Index.

Note: Some of these lists are generated for you when you create output. In this case, you do notneed to create a topic reference for them.

4. Select the new booklist and click Edit ➤ Element Properties.

5. Type a title, click Create, and select a DITA Topic or DITA Map template.

XMetaL | Working with DITA bookmaps | 141

6. Type a name for the file.

Create and insert a glossaryYou create glossary terms and definitions in a single file or group of files.Your bookmap can contain one ormore glossary files. XMetaL provides templates for creating single or multiple glossary entries. Glossaryterms are merged when you create output.They are merged and sorted according to the language you specify(in the xml:lang attribute) when you use the XMetaL Enhanced deliverable types.

1. In the XML view of the bookmap, place the cursor inside the book lists component and add a glossary listusing the Element List.

2. Click File ➤ New and select the DITA Glossary tab.

3. Create a new file using one of the following templates:

• Glossary - Multiple. This template lets you enter one or more glossary terms.• Glossary - Single. This template lets you enter a single glossary term.

4. Enter the term(s) and definition(s) in the new glossary file and save.

5. In the XML view of the bookmap, click inside the <glossarylist> element.

6. Using the Attribute Inspector, specify a value for the navtitle attribute .

7. In the <glossarylist> element, click Insert ➤ Topic Reference and select the glossary file.

142 | XMetaL | Working with DITA bookmaps

Publishing documents

XMetaL uses the DITA Open Toolkit to transform DITA content into an output deliverable.

You supply settings to the DITA Open Toolkit through the combination of an output format and a deliverabletype.

A deliverable type specifies an output format and additional configuration settings. For example, you canapply your own CSS stylesheet to change the appearance of HTML output files. Deliverable types also supportconditional settings.

XMetaL includes deliverable types that you can use to publish your documents out of the box. By default,some deliverable types are disabled.To view them, click Show disabled deliverable types in the ConfigureOutput Options dialog.The output format specified for a deliverable type is indicated in the Edit DeliverableType dialog.

Table 12: Deliverable types

DescriptionName

Produces production-quality print output out of the box using XEPand a fully configurable set of parameters.

XMetaL Enhanced PDF via RenderX XEP

Produces production-quality print output out of the box using XEPand a fully configurable set of parameters. Also includes support

XMetaL Enhanced PDF via RenderX XEP andAcrobat Distiller

for EPS graphics. Requires purchase and installation of AdobeAcrobat Distiller.

Produces a single compiled Microsoft HTML Help CHM file.Includes support for map and alias files for context-sensitive Help.Requires Microsoft HTML Help Workshop.

HTML Help (CHM)

Produces a single HTML file with a linked table of contents.Includes support for custom CSS, header, and footer files. The

Single HTML file

‘Single HTML File (example)’ deliverable type contains specificCSS, metadata, header, and footer files.You can modify thesefiles to produce custom output.

Produces an HTML file for each topic reference and a root HTMLfile for the map. Includes support for custom CSS files andheader/footer files.

Multiple HTML files

Preview options

Preview options let you specify a deliverable type for previewing content. When you select View ➤ PagePreview, XMetaL applies the specified deliverable type to your DITA topic or map.

Output log

XMetaL includes processing messages in an output log.You can view this file by clicking File ➤ View OutputLog. The location of the log file is indicated by the path specified for LOGFILE_DIR in the log file.

You can set the log to always open after you generate output by setting the cmd_always_open_log parameteras follows:

cmd_always_open = yes

XMetaL | Publishing documents | 143

XMetaL Enhanced deliverable typesYou can generate production-quality print output out of the box using the ‘XMetaL Enhanced PDF via RenderXXEP’ and ‘XMetaL Enhanced PDF via RenderX XEP and Acrobat Distiller’ deliverable types.You can customizethe output that you create with them through a fully configurable set of parameters.

These deliverable types work with the RenderX XEP print formatter that is included with XMetaL Author.Theyhave also been tested with Antenna House XSL Formatter.They are optimized to produce book-type deliver-ables that include book lists such as a table of contents and index and book divisions such as parts andchapters.

The XMetaL Enhanced deliverable types feature processing improvements over previous print deliverabletypes and the default toolkit ‘PDF2’ output. For example, the <booktitlealt> and <bookpartno> appear asthe subtitle and part number on the title page. Page numbers appear for topics contained within front matter.By default, page numbers and the book title appear in the footer. Headers are separated by a horizontal line.

The appearance of the book deliverable features improved default margins. The first page of chapters, parts,and appendixes are space-efficient and feature an increased right margin to accommodate tables, definitionlists, and images. They do not include the wide left margin or mini-TOC in the default toolkit processing.Chapter headings are right-justified. Topic headings are not separated by a horizontal line.

Book output features improved typography, with a sans-serif font for titles, headers, and footers.<menucascade>elements use a greater-than (‘>’) symbol instead of the curved arrow used by the toolkit.

Icons for notes, tips, and other note-type elements have been improved and table rows now have a graybackground.

Other enhancements

Other enhancements to the DITA Open Toolkit processing include the following.

• Seamless integration into the authoring environment. XMetaL allows you to generate output directly fromthe authoring interface through easy-to-understand menus and dialogs. Authors can preview output to seehow changes affect output.

• Ease of configuration and troubleshooting. XMetaL includes a default set of deliverable types for the variousoutput formats supported by the toolkit. Authors can easily change and add new deliverable types. Admin-istrators can deploy custom deliverable types across an authoring team. Authors can configure output usingconditions to produce, for example, an audience-specific deliverable. Processing errors are easily identifiedby formatting in the output log.

• Single HTML file output format. From your map, you can create a single HTML file that includes a table ofcontents. The ‘Single HTML file (example)’ deliverable type demonstrates custom styling, and headers andfooters.

• Glossary merging and sorting. Glossary entries are merged from multiple sources and, in the XMetaLEnhanced deliverable types, sorted according to the language specified.

• Technical support. Customers can contact XMetaL Technical Support for assistance with configuring theDITA Open Toolkit. Support policies are available from the XMetaL website.

• Improved documentation. Detailed documentation on how to customize PDF, HTML, and CHM output isprovided.

144 | XMetaL | Publishing documents

Sample output

An example of a book-type deliverable created using an XMetaL Enhanced deliverable type is included at..\XMetaL\Author\Evaluation Guide\.

Customizing output

You can customize the print output by specifying parameters. For example, you can change page margins,use different fonts, or control the header and footer text. For information, see PDF parameters on page 184.

DITA Open ToolkitThe DITA Open Toolkit is a Java-based implementation of the OASIS DITA Technical Committee’s specificationfor DITA DTDs and schemas. The toolkit transforms DITA maps and topics into deliverable formats.

The DITA Open Toolkit is maintained by Sourceforge. New versions of the Toolkit and documentation areposted to the DITA Open Toolkit project page.You can download and install new versions of the DITA OpenToolkit. In order to take advantage of the new version when you generate output, you need to specify it as aparameter in XMetaL.You may also need to re-install other configuration files (for example, those used byRenderX).

The version of the DITA Open Toolkit that is installed with XMetaL is specified in the release notes.

For more information, see the DITA Open Toolkit User Guide.

Upgrade to a newer version of the DITA Open ToolkitYou can specify a newer version of the DITA Open Toolkit in a global or local parameter.

1. Download the ZIP archive containing the new version of the Toolkit.

2. Extract the contents of the archive to a folder on your C: drive, for example, C:\DITA_OT_NEW.

3. In XMetaL, select Tools ➤ Configure Output and click the Advanced tab.

4. Type the following lines in the Other Output Parameters box: DITA_OT_DIR = C:\DITA_OT_NEW.

Advanced optionsYou can specify advanced options on a global basis or separately for each deliverable type.

Global output options let you specify elements to display in your output and debugging options.

Local options let you specify a stylesheet, choose a viewer application, or disable the deliverable type.

When you specify a stylesheet, you override one of the default transform (XSL) files in the DITA Open Toolkit.Specifying a stylesheet has the effect of setting the ‘args’ parameter. For more information, refer to the DITAOpen Toolkit User Guide.

Note: This option is recommended for advanced users who are familiar with the DITA Open Toolkit andXSL.


Do thisTo specify

Click Tools ➤ Configure Output. Click the Advanced tab.The settings you make here apply to all deliverable types.

Global options

Click Tools ➤ Configure Output. Select a deliverable typeand click Edit. Click the Advanced tab. The settings youmake here apply to the selected deliverable type only.

Local options

You can specify additional parameters as name/value pairs in the Other Output Parameters box.

Specifying a languageThe language specified for your map or bookmap is used by processors such as the DITA Open Toolkit todetermine sort order in booklists such as glossaries.

You can specify a language in the following locations:

1. As a property of your map or bookmap. The Language property is displayed in the Other Attributes tab ofthe Properties dialog.You can also set the value for xml:lang through the Attribute Inspector. This valuetakes priority over other language settings.

2. As a property of a component of a map or bookmap, such as a <glossarylist> element. The Languageproperty is displayed in the Other Attributes tab of the Properties dialog.

3. As a global or local parameter, for example:

DSDK_PARAM_ditalocale=fr

ANT_PARAM_args.dita.locale=fr

Language values are based on ISO-3166 Country Codes and RFC 3066 Language Codes. If you do notspecify a language, it is assumed to be ‘en-us’ (US English).

Refer to the DITA Open Toolkit User Guide for more information on localizing your DITA content.

ChunkingChunking refers to how the content you see in XMetaL is organized in files when you generate output froma DITA map.

By default, the structure of the output from a DITA map reflects that which is represented in the Map Editoror XML view of the map, that is, topics (including composite topics) are saved as individual HTML files.However, you can specify different chunking behaviors, for example:

• You can split composite topics into several output files

• You can merge a group of topics into a single output file

• You can re-use a single topic from a composite topic and create output for that topic in a single file

• You can create a single navigation chunk (for example, a table of contents) within the entire contents of amap


Set chunkingYou can change the way content is chunked (divided or merged into new output documents) by setting thechunk attribute.You can specify chunking behavior on most map elements. The value of the chunk attributeconsists of one or more space-delimited names.

1. Select an element in the Map Editor.

2. Click Edit ➤ Element Properties.

3. Click the Special Attributes tab and enter a value in the Chunk field.

For more information about allowed values, see the DITA Architectural Specification.

Viewing online Help outputSome online Help formats require a specific viewer.

If the output format specifies a compiled file (for example, an HTML Help .chm file), you also need theappropriate compiler in order to generate output.

SoftwareFormat

HTML Help Workshop. Contains viewer and compiler. Available for download from the Microsoft

Developer Network.

HTML Help

JavaHelp viewer. Distributed as part of the JavaHelp 2.0 platform. Available for download from Sun

Microsystems.

JavaHelp

Eclipse viewer. Distributed as part of the Eclipse platform. For information about deployment options,

see IBM Developer Works.

Eclipse Help

Create a deliverable typeYou can create a new deliverable type that specifies an output format and other settings.

1. Click Tools ➤ Configure Output.

2. Click Add and select an output format, then click Continue.

Note: Some output formats require that you have the appropriate compiler installed.You must installthe compiler in order to be able to generate output using the deliverable type. For example, you mustinstall Microsoft HTML Help Workshop before you can generate output using the HTML Help (CHM)deliverable type.

3. Type a name for the deliverable type.

The name you choose for your deliverable type can reflect a specific document and format.

4. If applicable, specify stylesheets and other options as determined by the output format. These include fileformat extension (for HTML) and related links (for PDF).


Edit a deliverable typeYou can edit a deliverable type through the Edit Deliverable Type dialog.


2. Select a deliverable type and click Edit.XMetaL displays the Edit Deliverable Type dialog.

3. Specify options as necessary in the General tab.

By default, an output folder is created in the same folder as the source file. To specify a location for youroutput folder, click Specify a folder and select a folder.

OptionsDeliverable type

You can specify a custom stylesheet and header and

footer files.You can choose an extension for output files.

Multiple HTML files, Single HTML file

You can specify an alias and map file.HTML Help (CHM)

You can choose to show related links in output.XMetaL Enhanced PDF

4. Optional: Click the Advanced tab and specify advanced options.

Set preview options


2. Click the Preview tab.

3. Select a deliverable type for previewing DITA topics and maps.

Generate outputYou can generate output for a DITA topic or map in any of the supported output formats. Output specificationsare defined in the deliverable type.

1. Open a DITA map.

2. In the Map Editor, click File ➤ Generate Output For DITA Map.

3. Select a deliverable type.

4. Optional: Click Show/Hide Conditional Text and select conditions that you want to appear in the output.

After you have finished generating output, you can check the output log for errors (for example, missingimages) by clicking File ➤ View Output Log.

Extending your publishing optionsXMetaL Author provides a flexible framework for publishing DITA documents using the DITA Open Toolkit.


This framework enables users to publish documents in any of the standard formats, including PDF, CHM,and HTML. An output format specifies the file format of an output deliverable and, in the case of PDF, a printformatter. A print formatter is a third-party tool that renders XML content as PDF. Each output format specifiesa transformation type (transtype) that contains Java and XSL processing. Some transformation types arenative to the DITA Open Toolkit and some are supplied by XMetaL. Transformation types are specified in thepublishing configuration files.

Adminstrators may want to override the settings in the output formats or specify new output formats. Considerthe following scenarios:

• Users need to override default parameter settings in an output format on a consistent and repeated basis.For example, they may need to specify alternative stylesheets in order to make their output conform tocorporate style guidelines.

• Your organization needs to support additional targets as provided by new DITA Open Toolkit plug-ins. Forexample, you may wish to create an output format that supports a new print formatter.

Once you have created a new output format, you can distribute it to other users in a publishing configurationfile.

Table 13: Output formats

NotesName

Basic PDF output. Uses the DITA OT ‘pdf’ transtype.PDF via FO with default processing

Enhanced PDF output using XEP. Includes improved pagination, indexing, andtable layouts. Also referred to as the ‘Idiom plug-in’ or ‘Idiom FO 1.1’ in the DITAOpen Toolkit documentation. Uses the DITA OT ‘pdf2’ transtype.

Book via RenderX

Enhanced PDF output using XEP and a fully configurable set of parameters.Provides production-quality print output out of the box. Uses the XMetaL ‘pdf3’transtype.

XMetaL Enhanced PDF via RenderXXEP

Enhanced PDF output using XSL Formatter and a fully configurable set ofparameters. Requires purchase and installation of Antenna House XSL For-matter. Uses the XMetaL ‘pdf3’ transtype.

XMetaL Enhanced PDF via AntennaHouse XSL Formatter

Enhanced PDF output using XEP and a fully configurable set of parameters.Includes support for EPS graphics. Requires purchase and installation of AdobeAcrobat Distiller. Uses the XMetaL ‘pdf3’ transtype.

XMetaL Enhanced PDF via RenderXXEP and Acrobat Distiller

Single HTML file

Multiple XHTML files

HTML Help (CHM)

JavaHelp

Eclipse Help

Eclipse Content

The Text Processor for Typesetters(troff)

Rich Text Format (RTF)

DocBook


Table 14: Print formatters

DescriptionName

Provides support for the Basic conformance level in XSL-FO.Apache FOP

Provides support for the Extended conformance level in XSL-FO. This includesimproved pagination, indexing, and table layouts.You can set configuration options,

RenderX XEP

such as fonts and languages, through the RenderX Assistant. The Assistant isavailable through the Edit Deliverable Type dialog. Distributed under license.

Provides support for the Extended conformance level in XSL-FO. This includesimproved pagination, indexing, and table layouts.

Antenna House XSL Formatter

Publishing configuration filesThe XMetaL publishing settings consist of batch code and parameters as specified in configuration files.

Batch code is executed when users generate output for a DITA topic or map. Users can supply values to thebatch by setting parameters. These values are used by the DITA Open Toolkit when generating output.

Table 15: Publishing configuration files

DescriptionName

Contains parameter settings and batch code for outputformats.

The <globals> element contains parameters that applyto all output formats. The <config> elements containparameters for specific output formats.

..\XMetaL\Author\DITA\XACs\shared\renditions\print_dita12.xml

Contains parameter settings for deliverable types.

The <globals> element contains parameters that applyto all deliverable types.The <config> elements contain

..\Documents and Settings\<user_name>\ApplicationData\SoftQuad\XMetaL\5.0\ print_local.xml

parameters for specific deliverable types. These set-tings override parameters of the same name inprint_dita12.xml.

The <base_config> ID attribute references a <config>element (that is, an output format) in print_dita12.xml

Specifying parametersYou can change the way you generate output, including the appearance of your output deliverable, byspecifying parameters.

You can specify parameters either by setting options in fields and checkboxes or by typing. Parameters canbe global or local.Your settings are stored in the publishing configuration files.

Do thisTo specify

Click Tools ➤ Configure Output. Click the Advanced tab.

The settings you make here apply to all deliverable types.

Global parameters

Click Tools ➤ Configure Output. Click Configure Output.

Select a deliverable type and click Edit. Click the Advanced

Local parameters


Do thisTo specify

tab. The settings you make here apply to the selected

deliverable type only.

Parameter sets

You can use the following parameter sets:

• XMetaL parameters. These are described in the print_dita12.xml configuration file.

• Java-based parameters and Ant-based parameters. These are described in the DITA Open Toolkit UserGuide. Some output formats use Java-based parameters, others use Ant-based parameters.

Tip: You can check the output format used by your deliverable type by clicking Tools ➤ ConfigureOutput. Then select your deliverable type and click Edit.

Table 16: Parameter sets by output format

AntJava

HTML Help (CHM)Multiple XHTML files

Structured FrameMakerPDF via FO with default processing

XMetaL Enhanced PDF via RenderX XEPJavaHelp

XMetaL Enhanced PDF via Antenna House XSL FormatterEclipse Help

XMetaL Enhanced PDF via RenderX XEP and AcrobatDistiller

Eclipse Content

The Text Processor for Typesetters (troff)

Rich Text Format (RTF)

DocBook

Book via RenderX

Single HTML file

Parameter syntax

You can type parameters in the Other Output Parameters box in the Advanced tab. Parameters consist ofname/value pairs. Check the documentation for valid values.

For Java parameters, the format is as follows:

DSDK_PARAM_<parameter name> = <parameter value>

For Ant parameters, the format is as follows:

ANT_PARAM_<parameter name> = <parameter value>

For example, to specify the ‘logdir’ parameter in the ‘Single HTML file’ output format, type the following:

DSDK_PARAM_logdir = html

To specify the same parameter in the ‘XMetaL Enhanced’ output format, type the following:

ANT_PARAM_args.logdir = html


Note: Ant parameters may contain more than one segment (denoted by the ‘.’ character).

Creating and modifying output formatsThere may be cases in which you need to create or modify an output format to support new requirements fordeliverables.

Consider the following scenarios:

• Users need to override default parameter settings in an output format on a consistent and repeated basis.

• Your organization needs to support additional targets as provided by new DITA Open Toolkit plug-ins. Forexample, you may wish to create an output format that supports a new FO processor for enhanced PDFoutput.

Once you have created a new output format, you can distribute it to other users in a publishing configurationfile.

Create an output formatYou can create a new output format by creating an XML configuration file and saving it in the same folder asprint_dita12.xml.You can distribute new configuration files in order to give all users access to the newoutput format.

1. Open print_dita12.xml in a text editor.

2. Create a new XML document that contains the following markup:

• An XML declaration• The print configuration DOCTYPE declaration: <!DOCTYPE print SYSTEM "print_config.dtd">• A single <print></print> root element• Optionally, a <globals></globals> element that contains settings that apply globally to all output

formats in the new configuration file. Refer to print_dita12.xml for an example.

3. Copy an existing <config> element from print_dita12.xml and paste it into the <print> element inthe new configuration file.

You may wish to choose a configuration that has settings similar to those you wish to use in the newconfiguration. For example, if your new configuration is based on HTML Help (CHM) output, copy andpaste the HTML Help configuration.

4. Type a unique ID for the new <config> element.

New deliverable types that you create for this output format will refer to this ID.

5. In the <config_title> element, type a unique title for the new configuration.

6. Add new parameters or change settings for existing parameters.

Parameters are specified in <instruction> elements.

7. Change the batch code as required and save the file in the same folder as print_dita12.xml.

You can now create a deliverable type that uses the new output format.

Modify an output formatTo modify an output format, change the contents of print_dita12.xml, the publishing configuration file thatcontains parameters for output formats.

1. Open print_dita12.xml in a text editor.

2. Scroll to the output format that you wish to modify.

Output formats are specified in <config> elements.


3. Add new parameters or change settings for existing parameters.

Parameters are specified in <instruction> elements.

TroubleshootingWhen you generate output, you may receive error messages in the output log, or output may fail.

If you cannot generate output, you can check and debug the log file. In the log, warnings are surrounded bya yellow box and errors and warnings are surrounded by a red or orange box.You can jump to the next orprevious warning or error by pressing Ctrl+Down Arrow or Ctrl+Up Arrow.

You can also refer to the DITA Open Toolkit User Guide and related online user forums. Issues related togenerating output are also described in the release notes.

You can also check the following:

• Check to see if a file with the same name (for example, a CHM or PDF file) as the one you are currentlygenerating is open. Close the file and re-generate.

• If you are generating output from a DITA topic file that is saved with a ‘.dita’ extension, check to see thatyou have included the following parameter in your deliverable type: ‘DSDK_PARAM_ditaext = .dita’ (foroutput formats that use Java) or ‘ANT_PARAM_dita.extname=.dita’ (for output formats that use Ant) andre-generate.

• The contents of the topics and the map are valid.

• Ensure that all link elements such as <topicref> and <xref> point to a target that exists.

• If your CHM file is written to a computer other than your own (for example, a network drive), you may notbe able to view the contents. Copy the CHM file to your local drive.

File and folder naming rules

The DITA Open Toolkit has requirements for file and folder names. Problems with file and folder names maycause publishing to fail. Check the following:

• The file extensions of the topic references in your map are of one type; they must all be either ‘.xml’ or‘.dita’.

• Your map file has the extension ‘.ditamap’.

• All files are stored on the same drive letter.

• File names do not contain punctuation except for the dot (.) before the file extension.

• Folder names in paths (for example, in <xref>, <image> and <topicref> elements) do not contain spacesor punctuation.


Working with conditions

In DITA, you can create versions of your content without having to maintain more than one set of sourcecontent by using conditions.

DITA defines the following default conditions:

• Audience

• Platform

• Product

You can define additional conditions either by creating specialized conditional processing attributes or byusing the otherprops attribute.You can use this set of conditions to support the workflow required by yourorganization. For example, you may have some content intended for administrators, other content intendedfor users, and content intended for both audiences. By using conditional text, you can indicate which sectionsof your content is intended for each of the audiences.You can style your conditions so that conditional contentis easy to identify.

You can specify which conditions to include in your output through the Generate Output dialog. If you specifymultiple conditions on an element, it is included in the output if any of the conditions specified are met.

Condition configuration file

Conditions are defined in ..\XMetaL\Author\Conditional Text\configs\ct_config.xml. Each conditionis defined by an <attribute> element and values.

The following extract from the condition configuration file defines the Audience condition and the values‘Administrator’ and ‘User’. The title attribute contains the user-friendly name that appears in the XMetaLinterface.

<attribute name="audience" title="Audience"> <value name="administrator" title="Administrator" /> <value name="user" title="User" /></attribute>

You can modify these values to support the requirements of your organization. For example, you may needto add the value ‘Evaluator’ if you need to include content that is relevant to evaluators only.

Creating new conditions

To create a new condition and values, you can add a new <attribute> element to the condition configurationfile. The name attribute value must be a valid conditional processing attribute name as defined in your DITADTDs. The following example uses a value of ‘otherprops’ to create a condition called ‘Release’ and thevalues ‘Beta’ and ‘1.0’.

<attribute name="otherprops" title="Release"> <value name="beta" title="Beta" /> <value name="1.0" title="1.0" /></attribute>

154 | XMetaL | Working with conditions

Apply a condition

1. Highlight the text or element to which you want to apply a condition.

2. Click Reuse ➤ Apply/Remove Conditions.

3. Select the range to which the condition will apply.

This can be the current element or selection, or any of its ancestors. In paragraph text, this can be a portionof the paragraph text (phrase-level) or the entire paragraph (paragraph-level).

4. Select and expand an attribute (e.g., Audience).

5. Click the check box for the value you want to set for the attribute.For example, if you want the text you selected to be for the administrator audience only then check theAdministrator check box.

You can click more check boxes to specify multiple conditions.

Display conditions in previews or outputWithin a deliverable type, you can specify all of the conditions you wish to see when you preview content orgenerate output. Advanced options let you export your settings to a DITAVAL file or to use another DITAVALfile. DITAVAL files are stored in ..\XMetaL\Author\DITA\XACs\shared\renditions\filters.

1. Open a DITA map file.

2. In the Map Editor, select File ➤ Generate Output For DITA Map.

3. Select a deliverable type and click Show/Hide Conditional Text.

4. Expand the list of attributes you want to show or hide conditional text for (e.g., Audience).

5. For each value, indicate whether you want it to be visible. If the check-box is checked, then all conditionaltext for that attribute value is visible in previews and output that you create using this deliverable type.

6. Optionally, click Advanced and specify advanced settings.

Style a conditionYou can control how conditions appear in the document window.

Note: This feature is disabled for limited users under Citrix.

1. Click Reuse ➤ Style Conditional Text.

2. Expand the list of attributes (e.g., Audience).

3. For each attribute value, indicate the following:

• Text color• Highlight color• Format

XMetaL | Working with conditions | 155

Modify conditionsTo modify conditions, you can customize the values for the Audience, Platform, or Product conditions or youcan add an otherprops attribute and supply values for it. Changes are effective when you re-start XMetaL.

1. Close XMetaL.

2. Open ..\XMetaL\Author\Conditional Text\configs\ct_config.xml in a text editor.


• Change the existing values for the Audience, Platform, and Product conditions• Add a new attribute with the name 'otherprops' and values

Note: Multiple values are space-delimited.

Here is an example of multiple values:

<attribute name="audience" title="Audience"> ... <value name="user evaluator" title="User" /></attribute>

156 | XMetaL | Working with conditions

Working with DITA specializations

You can use XMetaL to create content that is based on your DITA specialization.

To do so, you must first configure XMetaL and create a specialized template.You can then modify the defaultstyle sheets to add or change formatting for base DITA elements and your specialized elements. The stepsare similar to those for creating an XMetaL customization. To take advantage of the formatting and cus-tomization options, you should be familiar with the following:

• DITA specializations

• XMetaL customizations

• Document type declarations

• Catalog files

• CSS

• Forms

You can configure the XMetaL user interface to perform functions with your specialized DITA DTD, for example,with custom menus and toolbars. See the XMetaL Specialization Guide for more information.

For information about creating and deploying customizations, see the XMetaL Customization Guide.

Before you begin

You should be familiar with specialization concepts as described in the DITA Architectural Specification.

Check to see that the system IDs in your specialization DTD files resolve correctly.

It is recommended that you create a folder for your specialization DTD files in the ..\Program Files\CommonFiles\XMetaL Shared\DITA_OT folder for the following reasons:

• The DITA Open Toolkit requires access to the specialized dtd. This is provided by catalog entries addedto catalog-dita.xml and/or catalog-dita_template.xml. Since catalog files denote paths in a mannerrelative to the catalog file itself, it is easiest to formulate paths if the specialized DTD is nearby.

• Specializations must include topic.mod and similar stock DITA entities; relative paths for system IDs canbe formulated easily from demo specialization examples, which have relative path system IDs that resolveto the DITA_OT\dtd folder.

• For easy identification of specialization folders in the event of an un-install or re-install.

Configure XMetaL

Note: Tools ➤ Select Specialized DITA DTD is disabled for limited users under Citrix.

1. Create a folder for your specialization.For example: ..\Program Files\Common Files\XMetaL Shared\DITA_OT\demo\faq.

2. Place your specialized DTD files in the specialization folder.

These include .dtd files and any modules.

Note: The system IDs in your specialization DTD must resolve correctly.

XMetaL | Working with DITA specializations | 157

3. Start XMetaL.

4. Click Tools ➤ Select Specialized DITA DTD and choose your specialized DITA DTD.

5. Choose the base document type that is most similar to the specialized document type (for example, Topic)and type the public ID for the specialized DTD. Do not include quotation marks.Here is an example of a public ID:

-//IBM//DTD DITA FAQ//EN

6. Click OK.XMetaL creates a customization folder for your specialization., for example,..\Author\DITA\XACs\faq_shell.

7. Close and re-start XMetaL.

8. If you want to create reusable components from your specialized topic, add an entity to the reusablecomponents entity file, ..\Author\DITA\DITA_OT_DTD\dcspecialized-typemods.ent.For example,

<!ENTITY % faq-shell-mod SYSTEM "C:\Program Files\Common Files\XMetaL Shared\DITA_OT\demo\faq\faq.mod">%faq-shell-mod;

Create a templateOnce you have configured XMetaL, you can create a template so that authors can create new documentsusing your specialization.

1. Select File ➤ New.

2. In the General tab, select Blank XML Document.

3. Select your DTD.For example, ..\XMetaL\Author\DITA\XACs\faq_shell\faq_shell_ditabase.dtd.

4. Add elements and attributes your template requires in order to be valid using the Element List and AttributeInspector.

5. Once you have created a valid document, switch to Plain Text view and remove the path segments and"_ditabase" portion of the filename in the document type declaration.For example,

<!DOCTYPE faq SYSTEM "faq_shell.dtd">

6. Change the keyword SYSTEM to PUBLIC and add the public ID for this document type, and simplify thesystem ID.For example,

<!DOCTYPE faq PUBLIC "-//IBM//DTD DITA FAQ//EN" "faq_shell.dtd">

7. Run the ‘DITA Configuration: Save Copy as Template’ macro.

This macro removes all ID attributes and all attributes of type class, domains, xmlns:ditaarch, andditaarch:DITAArchVersion.

8. Save the file with the extension ‘.xml’, ‘.dita’, or ‘.ditamap’ in your DITA templates directory, specifyingUTF-8 encoding type.

Test your template by clicking File ➤ New.

158 | XMetaL | Working with DITA specializations

Apply custom formatting

1. Open the CSS stylesheet for your specialization, for example,..\XMetaL\Author\DITA\XACs\faq_shell\faq_shell_ditabase-specialized.css.

2. Add selectors and styles for your specialized DITA DTD elements.

Create a customized XMetaL form

1. Copy the form that you wish to use and paste it in the customization folder for your DITA specialization.

2. Modify the form as required using the XMetaL Forms Layout tool.

Generate IDs for PDF output

1. Select File ➤ Open and choose an XML document with a specialized topic, section, title, or exampleelement. (These elements have, by default, specified ID values.)

2. Select Auto-assign element IDs and click Options.

3. Move the specialized topic, section, title, and example elements from the Available list to the Selected list.

Overriding base formattingYou can change the formatting of base DITA elements and see the results in all DTDs that use them.

You can also change the formatting for your specialized elements. The CSS cascade determines which ruleto use by using the ‘class’ attribute.

To override formatting for base DITA elements, edit the overriding CSS styles for DITA base elements.

Table 17: Cascade order

SpecifiesLocationCSS file

Baseline CSS styles for ditabase ele-

ments such as "topic/topic" and

"topic/p"

..\XMetaL\Author\XACs\sharedditabase-base.css

Overriding CSS styles for re-style

ditabase elements such as "topic/topic"

and "topic/p"

..\XMetaL\Author\DITA\XACs\ditabaseditabase-base-override.css

Baseline CSS styles for ditabase ele-

ments such as "task/task" and "ref-

erence/reference"

..\XMetaL\Author\DITA\XACs\sharedditabase-derived.css

XMetaL | Working with DITA specializations | 159

SpecifiesLocationCSS file

Overriding CSS styles for re-style

ditabase elements such as "task/task"

and "reference/reference"

..\XMetaL\Author\DITA\XACs\ditabaseditabase-derived-override.css

Specialized CSS styles for specialized

elements such as "faq/faq"

..\XMetaL\Author\DITA\XACs\{$spe-

cialized_dtd}

{$specialized_dtd}_ditabase-spe-

cialized.css

Changing the display font size

You can change the size of the display font. For example, to increase the default font sizeof a document, type the following in ditabase-base-override.css:

$DOCUMENT {font-size: 18px;}

160 | XMetaL | Working with DITA specializations

Working with a content repository

XMetaL Connector is a repository integration layer that provides rapid access to your content repositorythrough an adapter, which is a software driver for your particular repository. The adapter provides access torepository operations, such as opening files and check in/check out operations, through XMetaL dialogs andmenus. The adapter is provided and installed by a system administrator.

Note: The availability of repository functionality is determined by the adapter. Refer to your repositorydocumentation for details.

Table 18: Common repository operations

NotesClick this:To do this:

Repository ➤ Open Checked-OutDocument

Open a document that you havechecked out

Repository ➤ Explore RepositoryExplore a repository

You may check in a document only if itis currently open for editing.

Repository ➤ Check In DocumentCheck in a document

You may check out a document only ifit is currently open for viewing. When

Repository ➤ Check Out DocumentCheck out a document

you check out a document, the currentview of the document is replaced withthe latest version of the document.

The document reverts to its previousversion.

Repository ➤ Undo CheckoutUndo checkout of a document

Repository ➤ Document PropertiesView document or map properties

You must set the URL for the repositorybefore accessing files for the first timeor if you switch repositories.

Repository ➤ Repository OptionsSet the URL for the default repository

Some repositories require that you logon before any repository operations areallowed.

Repository ➤ Log On to RepositoryLog on to a repository

Repository ➤ Log Off from Repos-itory

Log off from a repository

Open a repository map or topic fileWhen you open a DITA-based repository map file, you have the option of downloading all referencedcomponents (for example, reusable components).You may wish to do this in order to improve performance.


• Click Repository ➤ Open from Repository and select a topic or map file.• Open a map file on a repository and double-click a topic or map reference. If you have enabled this

option, XMetaL gives you the option to view or edit the file.

XMetaL | Working with a content repository | 161

Create a new repository fileThe preferred method of creating a new repository document is by using a repository template. When youadd referenced components (for example, images and links) to the new file, you will have access torepository-specific operations (for example, advanced search) if your adapter supports it.

1. Click Repository ➤ New from Repository Template.

2. Select a template.

Create a new repository map

1. In the Map Editor, click Repository ➤ New Map from Repository Template.

2. Select a template.

Repository toolbarYou can access and manage documents in a repository through the repository toolbar.

Table 19: Repository toolbar commands

DescriptionMenu commandName/TooltipButton

Displays repository contentsRepository ➤ New fromRepository Template

New from Repository Tem-plate

Displays repository contentsRepository ➤ Open fromRepository

Open from Repository

Displays a search dialogRepository ➤ ExploreRepository

Explore Repository

Displays repository contentsRepository ➤ Check InDocument

Check In Document

Displays repository contentsRepository ➤ Check OutDocument

Check Out Document

Reverts to previously savedversion of the document

Repository ➤ UndoCheckout

Undo Checkout

Displays information aboutthe current document

Repository ➤ DocumentProperties

Document Properties

162 | XMetaL | Working with a content repository

Adapter configuration fileConfiguration files are located at ../XMetaL/Author/CRCL/configs. Each adapter instance must have aconfiguration file.

Note: Only one configuration file can have the AdapterInstance default attribute set to True.

XMetaL | Working with a content repository | 163

Working with XMetaL Reviewer comments

If you load a document that has been exported from XMetaL Reviewer, XMetaL Author identifies the documentas a Reviewer document and provides access to Reviewer functionality through the Comment menu.

For complete information about working with XMetaL Reviewer, refer to the product documentation.

Find comments


• If you know the approximate position in the document, you can search for the comment icon in thedocument pane. Click on the icon to select the comment in both the document pane and the ResourceManager.

• If you know some of the text in the comment itself, you can search for the comment text in the ResourceManager.

Filter comments

1. Click View ➤ Filter Comments.

2. Select options as required.

Integrate revisionsIf you want to accept a suggested revision, you indicate your acceptance by integrating the revision.

1. Select a revision by clicking on it.

2. Click Comment ➤ Integrate revision.

Change comment status

1. Select a comment by clicking on it.

2. Click Comment ➤ Change Status and select the new status.

Remove all comments

1. Select Comment ➤ Remove All Comments.

164 | XMetaL | Working with XMetaL Reviewer comments

Appendix A: Configuring XHTML and CHM output

You can use XMetaL to produce XHTML and Microsoft HTML Help (CHM) output using the DITA Open Toolkit.

The toolkit allows you to customize the appearance of your XHTML and CHM deliverables using CascadingStyle Sheets (CSS).You can also specify custom headers and footers in separate HTML files.You can savethese and other settings in an XMetaL deliverable type.

Specify the appearance of HTML pages, including fonts, colors, margins, andpadding. XMetaL Author includes default CSS files.

CSS files

Specify the header and footer content of every HTML page.You can createheaders and footers in separate HTML files. The content of these is copied intoyour HTML output.

Headers and footers

You specify custom CSS files and headers and footers within a deliverable type.XMetaL comes with a default set of deliverable types, which are named accordingto their output format (for example, ‘Multiple HTML files’).

XMetaL deliverable types

Before you begin, you must have the following:

• XMetaL Author 5.0 (or later) DITA Edition or XMetaL Author 5.0 (or later) Enterprise Edition

• A basic understanding of HTML and CSS

• A DITA topic or map file

Default CSS files

The following CSS file determines the base styling for your XHTML and CHM output:

• C:\Program Files\Common Files\XMetaL Shared\DITA_OT\resource\commonltr.css .This file includesselectors and styles for left-to-right output.

• C:\Program Files\Common Files\XMetaL Shared\DITA_OT\resource\commonrtl.css .This file includesselectors and styles for right-to-left output.

These files are copied to the folder that is created when you generate output. All HTML output files refer tothis file.You can copy and edit this file to create custom styling for your output.You specify your custom CSSfiles through the Edit Deliverable Type dialog.

Custom configuration folder

It is recommended that you store your custom configuration files (the CSS and header and footer files youcreate) in a separate folder within the ‘XMetaL Shared’ folder. Name the folder according to the deliverabletype. Here is an example for XHTML:

C:\Program Files\Common Files\XMetaL Shared\xhtml_custom

From now on, we will refer to this directory as [XMetaL Shared]\xhtml_custom.

Creating custom CSS filesYou can customize the appearance of your XHTML and CHM output files using custom CSS files. Begin bycopying the default CSS files.

XMetaL | Appendix A: Configuring XHTML and CHM output | 165

The default CSS files contain selectors and style specifications for your output including:

• Titles

• Lists

• Tables

• Paragraph text

• Notes

In the default CSS file, the .notetitle class selector (that is used to style note titles) is specified as bold.



.notetitle { font-weight: bold; }

To change styles, first copy the default CSS file to your custom configuration folder and rename it (for example,to ‘custom.css’).You can then edit the style specifications as required, or add new selectors. For example,to change note titles to bold and red for XHTML output, you can specify the following:



<div id="custom-header"> <h3>Acme Industries Help</h3></div>

The following is an example of a custom footer file:



<div id="custom-footer"><p class="copyright-notice">Copyright &169; 2007 Acme Industries. All rights reserved.</p></div>

166 | XMetaL | Appendix A: Configuring XHTML and CHM output

Note: Use numerical entities for symbols (‘&169;’ for the copyright symbol in the above example).

Once you have created your CSS file, you need to specify it in a deliverable type. When you do this, thecontent of the header and footer files is copied into the HTML output files.

Deliverable types and parametersYou specify your custom CSS, header, and footer files in a deliverable type. XMetaL saves the settings youuse for generating output as parameters.

You specify parameters through the Edit Deliverable Type dialog. The manner in which you specifyparameters depends on the output format:

• For XHTML output, you specify parameters by selecting files in ‘Stylesheets’ area of the General tab.• For CHM output, you specify parameters in the ‘Other output parameters’ box in the Advanced tab using

the syntax indicated.

Note: For both deliverable types, you need to specify the ‘copycss’ parameter in the Advanced tab.

Table 20: Deliverable type parameters

DescriptionParameterFile

Your custom CSS file.cssSpecific CSS

The file containing your custom header.The contents of this file are placedimmediately after the <body> tag in the HTML output files.

hdrPage header

The file containing your custom footer content. The contents of this file areplaced immediately before the </body> tag in the HTML output files.

ftrPage footer

Save settings in an XHTML deliverable typeOnce you have created your custom CSS and header and footer files, you can specify them in an XHTMLdeliverable type.


2. Select the ‘Multiple HTML files’ deliverable type and click Edit.


3. In the General tab, specify the settings for Specific CSS, Page header, and Page footer by clicking theBrowse button.


4. Click the Advanced tab and type the ‘copycss’ parameter in the Other output parameters box as specifiedbelow.


Note: Parameters for this deliverable type use Java syntax.

5. Click OK to close the Edit Deliverable Type and Configure Output Options dialogs.

You are now ready to generate output using the new deliverable type.

Save settings in a CHM deliverable typeOnce you have created your custom CSS and header and footer files, you can specify them in an HTML Help(CHM) deliverable type.


2. Select the ‘HTML Help (CHM)’ deliverable type and click Edit.


3. Click the Advanced tab and type the parameters indicated below in the Other output parameters box.


Note: Parameters for this deliverable type use Ant syntax.The paths specify the custom configurationfolder for CHM output.

4. Click OK to close the Edit Deliverable Type and Configure Output Options dialogs.

You are now ready to generate output using the new deliverable type.


Appendix B: Configuring PDF output

You can use XMetaL in conjunction with the DITA Open Toolkit to produce PDF output from your DITA topicsand maps. To produce PDF, XMetaL first transforms DITA-based content into an FO file (XML with formattingobjects) and then sends it to an FO processor, which renders it as PDF.

The toolkit allows you to customize your PDF output through a catalog-based custom configuration framework.No modification of the toolkit is necessary.

Custom configuration files determine the appearance of your PDF output, including:

• Page layouts

• Front matter

• Headers and footers

• Page body content

• Notes

• Fonts

Procedure overview

The process of making a custom configuration consists of adding configuration files to a customization directoryand making changes to the catalog file in that directory. The changes you make override the settings in thedefault catalog file. For more information, refer to README.txt in the customization folder.

The changes you make using the method described here affect the default toolkit processing, also referredto as the ‘Idiom plug-in’ or ‘Idiom FO 1.1’ in the DITA Open Toolkit documentation. This processing uses theDITA OT ‘pdf2’ transtype. Changes that you make to the default pdf2 processing affect all deliverable typesthat use the ‘Book via RenderX’ output format.

The XMetaL Enhanced output formats are a customization of the default toolkit processing. These outputformats use the XMetaL ‘pdf3’ transtype.You can make changes to them in the following ways:

• By modifying the XMetaL pdf3 transtype

• By setting parameters

If you choose to modify the XMetaL pdf3 transtype, you edit the files in the following folder:

C:\Program Files\Common Files\XMetaL Shared\DITA_OT\demo\xmfo\Customization

Changes that you make to the default pdf3 processing using either method affect all deliverable types thatuse the ‘XMetaL Enhanced’ output formats.

Custom configuration framework

By default, the toolkit uses the files in the following folder to generate PDF output:

C:\Program Files\Common Files\XMetaL Shared\DITA_OT\demo\fo

From now on, we will refer to this folder as [FO].

The set of files you create for your custom configuration must be located in the following folder:

XMetaL | Appendix B: Configuring PDF output | 173

C:\Program Files\Common Files\XMetaL Shared\DITA_OT\demo\fo\Customization

From now on, we will refer to this folder as [FO_CUSTOM].

Table 21: Configuration files

Custom configuration file/folderDefault file/folderComponent

[FO_CUSTOM]\catalog.xml[FO]\cfg\catalog.xmlCatalog file

[FO_CUSTOM]\fo\attrs\custom.xsl[FO]\cfg\fo\attrs\*.xslAttribute sets

[FO_CUSTOM]\common\artwork[FO]\cfg\common\artworkArtwork

[FO_CUSTOM]\fo\font-mappings.xml[FO]\cfg\fo\font-mappings.xmlFont mappings

[FO_CUSTOM]\fo\layout-masters.xml[FO]\cfg\fo\layout-masters.xmlPage layouts

[FO_CUSTOM]\fo\xsl\custom.xsl[FO]\xsl\fo\*.xslXSLT style sheets

[FO_CUSTOM]\common\vars\*.xml[FO]\cfg\common\vars\*.xmlVariables

[FO_CUSTOM]\common\index\*.xml[FO]\cfg\common\index\*.xmlIndex configurations

A custom configuration contains the following components:

The catalog file points to the other files in your custom configuration.Catalog file

Attribute sets contain formatting information such as fonts, colors, margins,padding, and borders. There are attribute sets for almost every DITA element.

Attribute sets

They are similar in concept to Cascading Style Sheets (CSS). Two excellentresources are http://www.dpawson.co.uk/xsl/sect3 as well as Mapping of elementsto the permitted properties

This folder includes images for your customization, such as those used in headersand footers. The accepted image formats are JPEG, GIF or PNG. PDF images

Artwork

can also be used. The default resolution is 120 dpi. Seehttp://www.renderx.com/reference.html#Graphic_Formats for more information.

Font files contain font mapping information.Fonts

Page layouts describe page characteristics such as dimensions, regions, andmargins.

Page layouts

XSLT style sheets contain templates that typically create formatting objects.Theyare frequently used in conjunction with variables.

XSLT style sheets

Variables define strings for use in headers, footers, and generated content.Variables

Index configurations control the display of the index, including sort order.Index configurations

Before you begin

Before you begin, you must have the following:

• An understanding of XML, XSLT, and XSL-FO

• A DITA topic or map file

• Document design specifications

174 | XMetaL | Appendix B: Configuring PDF output

http://www.dpawson.co.uk/xsl/sect3

http://www.dpawson.co.uk/xsl/sect3/els2prop.html

http://www.dpawson.co.uk/xsl/sect3/els2prop.html

http://www.renderx.com/reference.html#Graphic_Formats

• Font files (if you are using fonts that are not included in the Windows operating system)

Page layouts

Page layouts describe the design and order of pages in your document. They also define page regions andtheir size and placement.

The DITA Open Toolkit defines page layouts using the following mechanisms:

• Attribute sets

• Page masters

• XSL templates

Attribute sets

The toolkit uses attribute sets to control the display of regions within pages. For example, the attribute set‘topic.title’ specifies padding, margins and border styles for topic titles.



<xsl:attribute-set name="topic.title"> <xsl:attribute name="font-family">Sans</xsl:attribute> <xsl:attribute name="border-bottom">3pt solid black</xsl:attribute> <xsl:attribute name="margin-top">0pc</xsl:attribute> <xsl:attribute name="margin-bottom">1.4pc</xsl:attribute> <xsl:attribute name="font-size">18pt</xsl:attribute> <xsl:attribute name="font-weight">bold</xsl:attribute> <xsl:attribute name="padding-top">1.4pc</xsl:attribute> <xsl:attribute name="keep-with-next.within-column">always</xsl:attribute></xsl:attribute-set>

Custom attribute set processing

You can change the default page layout in your custom configuration. For example, you may want to createa title page that reflects the graphic standards of your company. Title pages typically contain the documenttitle, product name, and corporate graphics. The following example adds a background image to the titlepage.



<xsl:attribute-set name="__frontmatter"> <xsl:attribute name="text-align">left</xsl:attribute> <xsl:attribute name="color">#000</xsl:attribute> <xsl:attribute name="background-image">url(Customization/OpenTopic/common/artwork/bg_image.jpg)</xsl:attribute>

<xsl:attribute name="background-repeat">no-repeat</xsl:attribute> <xsl:attribute name="background-position">left top</xsl:attribute> <xsl:attribute name="padding">30mm 0 0 0</xsl:attribute></xsl:attribute-set>

Note: The source file for the background image file must be located in the artwork folder for your customconfiguration. The (source) path is:

[FO_CUSTOM]\common\artwork


The path to the background image in the xsl:attribute is the relative path required by the DITA OpenToolkit. This (destination) path is the path to the folder that is created during PDF processing:

[output directory]\pdf_out\Customization\OpenTopic\common\artwork

Page masters

Each document has a page sequence master that defines where page masters occur in a document. Pagemasters describe basic page layouts, such as margins and columns. Each page of a document is renderedby one of the page masters specified in the page sequence master.

The following is the default page master that is used to create the title page. This page master describes apage with a header and footer.



<fo:simple-page-master master-name="front-matter-first" page-width="8.5in" page-height="11in"> <fo:region-body margin-top="1.25in" margin-bottom="1in" margin-left="1.5in" margin-right="0.5in"/> <fo:region-before extent="1.25in" display-align="before" region-name="even-frontmatter-header"/> <fo:region-after extent="1in" display-align="after" region-name="even-frontmatter-footer"/></fo:simple-page-master>

Custom page master processing

You can change the default page master definitions in your custom configuration. For example, the followingcustom page master modifies the default title page layout:

• the page orientation is now landscape (11 inches wide x 8.5 inches high)

• all margins are set to 0.5 inches



<fo:simple-page-master master-name="front-matter-first" page-width="11in" page-height="8.5in"> <fo:region-body margin-top="0.5in" margin-bottom="0.5in" margin-left="0.5in" margin-right="0.5in"/> <fo:region-before extent="0.5in" display-align="before" region-name="even-frontmatter-header"/> <fo:region-after extent="0.5in" display-align="after" region-name="even-frontmatter-footer"/></fo:simple-page-master>


Headers and footers

Headers and footers typically include information such as page numbers, document titles, and product names.

The DITA Open Toolkit defines headers and footers using the following mechanisms:

• Attribute sets

• Variables

• XSL templates

Attribute sets

The toolkit uses attribute sets to control the display of content within headers and footers. For example, thefollowing attribute sets (‘__body__odd__footer ’ and ‘ __body__odd__footer__pagenum’ ) specify styles forthe footer content on odd-numbered pages of the document body.



<xsl:attribute-set name="__body__odd__footer"> <xsl:attribute name="text-align">right</xsl:attribute> <xsl:attribute name="margin-right">10pt</xsl:attribute> <xsl:attribute name="margin-bottom">10pt</xsl:attribute></xsl:attribute-set>

<xsl:attribute-set name="__body__odd__footer__pagenum"> <xsl:attribute name="font-weight">bold</xsl:attribute></xsl:attribute-set>

Custom attribute set processing

You can change the default styling of headers and footers in your custom configuration. For example, thefollowing attribute sets style the footer text in italics and the page number as normal text, colored red.


<xsl:attribute-set name="__body__odd__footer"> <xsl:attribute name="text-align">right</xsl:attribute> <xsl:attribute name="margin-right">10pt</xsl:attribute> <xsl:attribute name="margin-bottom">10pt</xsl:attribute> <xsl:attribute name="font-style">italic</xsl:attribute></xsl:attribute-set>

<xsl:attribute-set name="__body__odd__footer__pagenum"> <xsl:attribute name="font-weight">bold</xsl:attribute> <xsl:attribute name="color">red</xsl:attribute> <xsl:attribute name="font-style">normal</xsl:attribute></xsl:attribute-set>

Variables

You can use variables to manage strings in headers and footers, indexes, tables of contents, and othergenerated content. Variables can be localized, and additional variable files are named according to locale asdefined in ISO 639- 1 and ISO 316, for example, ‘en_US’.

Header and footer variables work together with header and footer XSL templates. They provide a frameworkfor localizing header and footer content.


The following are the default variables used by the toolkit to produce header content for odd-numbered andeven-numbered body pages. The even-numbered header contains the product name followed by a runningheader and page number; the odd-numbered header contains the same items in reverse order.

The values of the <param> elements are supplied to the insertVariable XSL template when it is called toprocess the Body odd header and Body even header variables (see XSL templates on page 178).



<variable id="Body odd header"> <param ref-name="prodname"/> | <param ref-name="heading"/> | <param ref-name="pagenum"/></variable>

<variable id="Body even header"> <param ref-name="pagenum"/> | <param ref-name="prodname"/> | <param ref-name="heading"/></variable>

Custom variables processing

The following example contains variables that override the default headers for odd-numbered and even-numbered pages. The even-numbered header contains the page number followed by the product revisioncode; the odd-numbered header contains the the running header followed by the page number.

The Body even header variable requires a param element called prodrev. (See XSL templates on page 178for sample XSL.)



<variable id="Body odd header"> <param ref-name="heading"/> | <param ref-name="pagenum"/></variable>

<variable id="Body even header"> <param ref-name="pagenum"/> | <param ref-name="prodrev"/></variable>

XSL templates

The DITA Open Toolkit includes a set of XSL templates that are used by other components for inserting andformatting content.

Using the default variable definition for headers of even-numbered body pages, the following template is usedby the body-even page master to insert the product name, heading, and page number variables. Formattingoccurs as a result of the ‘__body__even__header’ attribute set.



<xsl:template name="insertBodyEvenHeader">

<fo:static-content flow-name="even-body-header"> <fo:block xsl:use-attribute-sets="__body__even__header"> <xsl:call-template name="insertVariable"> <xsl:with-param name="theVariableID" select="'Body even header'"/> <xsl:with-param name="theParameters"> <prodname> <xsl:value-of select="$productName"/>


</prodname> <heading> <fo:inline xsl:use-attribute-sets="__body__even__header__heading"> <fo:retrieve-marker retrieve-class-name="current-header"/> </fo:inline> </heading> <pagenum> <fo:inline xsl:use-attribute-sets="__body__even__header__pagenum"> <fo:page-number/> </fo:inline> </pagenum> </xsl:with-param> </xsl:call-template> </fo:block></fo:static-content>

</xsl:template>

The insertVariable template call passes two parameters: theVariableID and theParameters.

The name of the variable in the locale file (e.g. [FO]\cfg\common\vars\en_US.xml)theVariableID

A set of parameters used by the the locale variable. In the above example, thelocale variable is Body even header, which uses the parameters pagenum,prodname, and heading:

theParameters


<variable id="Body even header"> <param ref-name="pagenum"/> | <param ref-name="prodname"/> | <param ref-name="heading"/></variable>

Custom XSL template processing

You can change the default toolkit processing by creating your own XSL templates that you can use togetherwith custom variable definitions.

The following example demonstrates how to create a custom header for even-numbered body pages. Thecustom header will have the page number and the document revision code.

To customize the header content, you need to create an XSL template, along with any variables the templatewill use. The value of the variable in this example, ‘Body even header’, is computed by two other parameters,pagenum and docrev. These parameters are passed when we call the insertVariable template from theinsertBodyEvenHeader template.

The pagenum parameter is merely the FO markup required to insert a page number. The docrev parametermakes use of the docRevision variable (see excerpt from [FO_CUSTOM]\fo\xsl\custom.xsl below).



<variable id="Body even header"> <param ref-name="pagenum"/> | <param ref-name="docrev"/></variable>



<xsl:variable name="docRevision"> <xsl:variable name="mapDocRevision" select="$map/@rev"/> <xsl:variable name="bkinfoDocRevision" select="/*[contains(@class, ' map/map ')]/@rev"/>


<xsl:choose> <xsl:when test="$mapDocRevision"> <xsl:value-of select="$mapDocRevision"/> </xsl:when> <xsl:when test="$bkinfoDocRevision"> <xsl:value-of select="$bkinfoDocRevision"/> </xsl:when> <xsl:otherwise> <xsl:value-of select="/descendant::*[contains(@class, ' topic/topic ')][1]/@rev"/>

</xsl:otherwise> </xsl:choose></xsl:variable>

<xsl:template name="insertBodyEvenHeader"> <fo:static-content flow-name="even-body-header"> <fo:block xsl:use-attribute-sets="__body__even__header"> <xsl:call-template name="insertVariable"> <xsl:with-param name="theVariableID" select="'Body even header'"/> <xsl:with-param name="theParameters"> <docrev> <xsl:value-of select="$docRevision" /> </docrev> <pagenum> <fo:inline xsl:use-attribute-sets="__body__even__header__pagenum"> <fo:page-number/> </fo:inline> </pagenum> </xsl:with-param> </xsl:call-template> </fo:block> </fo:static-content></xsl:template>

Note: For XSL templates that reference formatting objects (FO) markup, make sure to have the fo:namespace in the xsl:stylesheet element:



<?xml version='1.0'?><xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.1">

Page body content

Most page body content is formatted by attribute sets, which are named on a per-element basis.The followingexamples include some of the attribute sets that are used to format page body content.

Note: The __fo__root attribute set styles for the overall document. Elements that do not have an attributeset inherit from this set.

Note: Definition lists (<dl> elements) are rendered as <fo:table> elements, so their attributes areincluded in the table below.

Table 22: Default content attribute sets

Default file (in [FO]\cfg\fo\attrs)Attribute setsComponent

commons-attr.xsltopic.title, topic.topic.titleHeadings


Default file (in [FO]\cfg\fo\attrs)Attribute setsComponent

topic.title__content, topic.topic.title__content

section.title, example.title, fig.title

commons-attr.xsltopicBody text

body__toplevel, body__secondLevel

body

section

p

__fo__root

tables-attr.xsltable.titleTables

__tableframe__top, __tableframe__bottom

thead.row.entry, thead.row.entry__content

dl

dlentry.dt, dlentry.dt__content

dlentry.dd, dlentry.dd__content

commons-attr.xslnoteNotes

note__label

note__table

note__image__entry

lists-attr.xslul, ul.li, ul.li__label, ul.li__label__content, etc.Lists

ol, ol.li, ol.li__label, ol.li__label__content , etc.

steps-unordered, steps-unordered.step, etc.

steps, steps.step, steps.step__label, etc.

For example, the following excerpt from [FO]\cfg\fo\attrs\tables-attr.xsl shows the default styles for tableheadings:



<xsl:attribute-set name="thead.row.entry">  <xsl:attribute name="background-color">antiquewhite</xsl:attribute></xsl:attribute-set>

<xsl:attribute-set name="thead.row.entry__content">  <xsl:attribute name="margin">3pt 3pt 3pt 3pt</xsl:attribute> <xsl:attribute name="font-weight">bold</xsl:attribute></xsl:attribute-set>

Custom processing

To customize styles:

1. Locate the relevant default attribute set (see the table above).

2. Copy the attribute set to [FO_CUSTOM]\fo\attrs\custom.xsl.

3. Modify / add attributes as required.


In the following example, the background color for table headers is set to black. Table heading text is alsocustomized.


<xsl:attribute-set name="thead.row.entry">  <xsl:attribute name="background-color">black</xsl:attribute></xsl:attribute-set>

<xsl:attribute-set name="thead.row.entry__content">  <xsl:attribute name="color">white</xsl:attribute> <xsl:attribute name="margin">3pt 3pt 3pt 3pt</xsl:attribute> <xsl:attribute name="font-weight">bold</xsl:attribute></xsl:attribute-set>

Notes

Notes come in a variety of types:

• Regular notes

• Caution

• Attention

• Danger

The type of note is set through the type attribute using the Attribute Inspector in XMetaL.

By default, notes are preceded by text and an image, which are stored as variables. Variables are definedfor each note type. The following example shows how the note of ‘type=note’ is rendered.


<variable id="Note">Note</variable>...<variable id="note Note Image Path">Configuration/OpenTopic/cfg/common/artwork/hand.gif</variable>

Custom processing

You can change how notes are rendered by specifying your own preceding text and image. The followingexample shows a note of ‘type=note’ with no preceding text and a custom image.



<variable id="Note"></variable>...<variable id="note Note Image Path">Configuration/OpenTopic/cfg/common/artwork/corporate_note.gif</variable>

For further modification of notes, you can customize the placeNoteContent XSL template. The followingtemplate uses a custom attribute set.



<xsl:template name="placeNoteContent"> <fo:block xsl:use-attribute-sets="note" id="{@id}"> <fo:inline xsl:use-attribute-sets="note__label"> <xsl:choose> <xsl:when test="@type='note' or not(@type)">


<fo:inline xsl:use-attribute-sets="note__label__note"> <xsl:call-template name="insertVariable"> <xsl:with-param name="theVariableID" select="'Note'"/> </xsl:call-template> </fo:inline> </xsl:when> ... </xsl:choose> </fo:inline> ... </fo:block></xsl:template>

Front matter

Front matter consists of the pages at the front of a book that precede its main text, for example, the title page,copyright notice, dedication, and table of contents.

You can create front matter content by setting the outputclass attribute value on a topic.The following templateapplies to topics that have the outputclass attribute value of ‘frontmatter’.



<xsl:template name="createFrontMatter"> <fo:page-sequence master-reference="front-matter" xsl:use-attribute-sets="__force__page__count"> ... <fo:flow flow-name="xsl-region-body"> <xsl:apply-templates select="//topic[@outputclass='frontmatter']" mode="frontmatter" /> </fo:flow> </fo:page-sequence></xsl:template>

You also need to add a custom template.


<xsl:template match="topic[@outputclass='frontmatter']"/>

<xsl:template match="*" mode="frontmatter"> <xsl:apply-templates mode="frontmatter" /></xsl:template>

Now you can control how your front matter content is processed, and more importantly, use the toolkit templateswhere you want the default processing. For example, you might want to include images in your front matterusing the default placeImage template.


<xsl:template match="image" mode="frontmatter"> <fo:block> <xsl:call-template name="placeImage" select="." mode="" > <xsl:with-param name="imageAlign" select="@align" /> <xsl:with-param name="href" select="@href" /> <xsl:with-param name="height" select="@height" /> <xsl:with-param name="width" select="@width" /> </xsl:call-template> </fo:block> </xsl:template>


Fonts

You can control the fonts in your PDF output through attribute sets and the following font mapping files:

• [FO_CUSTOM]\fo\font-mappings.xml. This file maps one or more fonts to a logical font name.

• ..\Program Files\Common Files\XMetaL Shared\renderx\xep.xml. This file maps a font to a file.

LocalizationGenerated strings are specified in variable files. Variable files are named according to locale.

You can change the generated strings by editing the variable files as described in Custom configurationframework on page 173.

Note: If you are using the XMetaL Enhanced deliverable types (pdf3 transtype), modify the variable filesin the following location: C:\Program Files\Common Files\XMetaLShared\DITA_OT\demo\xmfo\Customization\common\vars.

Refer to the DITA Open Toolkit User Guide for more information about localizing your DITA content.

Debugging your custom configuration

A good way to troubleshoot your configuration is to examine the FO file before RenderX processes it.

By default, the toolkit deletes the FO file that is sent to the PDF processor.To change this behavior, commentout the line that deletes the file.



<delete> <fileset dir="${buildDir}" includes="stage?.*"/> </delete>

After you generate output, check your output directory for topic.fo. By looking at this file in a text editor,you can see if the result of your customized processing is correct.

PDF parametersWhen you use the XMetaL Enhanced deliverable types, you can customize your PDF output by settingparameters.

Customization files for PDF output are located in the following folder:

C:\Program Files\Common Files\XMetaL Shared\DITA_OT\demo\xmfo

From now on, we will refer to this directory as [xmfo].


Header and footer layout

Header and footer layout is defined in the following file:

[xmfo]\Customization\fo\xsl\custom.xsl

To define custom header and footer layout, you can modify parameters and templates defined in the followingfiles and copy them into ..\xsl\custom.xsl:

• [xmfo]\Customization\fo\xsl\xm_static_content.xsl

• [xmfo]\Customization\fo\xsl\xm_common_vars.xsl

Attributes for content styles

Attributes for content styles are defined in the following file:

[xmfo]\Customization\fo\attrs\custom.xsl

To define custom content styles:

1. copy the attribute set you require from the following folder:

[xmfo]\Customization\fo\attrs\xm-cfg

2. Paste the attribute set into [xmfo]\Customization\fo\attrs\custom.xsl and modify as required.

Page marginsPage margins set the space from the body content to the physical edge of the page. The top and bottommargin space is used for header and footer content.

Table 23: Parameters

DescriptionName

The top page margin is the distance from the body content to the physical top edge ofthe page. This area is used for header content.

xm.page.margin.top

The bottom page margin is the distance from the body content to the physical bottomedge of the page. This area is used for footer content.

xm.page.margin.bottom

The inner page margin is the distance from the body content to the physical inner edgeof the page (where the book is bound ). For single-sided output, set thexm.page.margin.inner value equal to the xm.page.margin.outer value.

xm.page.margin.inner

The inner page margin is the distance from the body content to the physical outer edgeof the page. For single-sided output, set the xm.page.margin.outer value equalto the xm.page.margin.inner value.

xm.page.margin.outer

Example

The top, bottom, inner, and outer page margins are, respectively, 1 inch, 1 inch, 0.75 inch,and 0.5 inch.

<xsl:variable name="xm.page.margin.top">1in</xsl:variable><xsl:variable name="xm.page.margin.bottom">1in</xsl:variable><xsl:variable name="xm.page.margin.inner">0.75in</xsl:variable><xsl:variable name="xm.page.margin.outer">0.5in</xsl:variable>


Headers and footersYou can configure the content, layout and styling of headers and footers using templates and variables.

Headers and footers are rendered as a three-column table, and you can set the relative width and the contentof each table cell.

The relative widths value for headers and footers table cells must be three integers from 0 to 9, separatedby a space. To center text in a header or footer, make sure the first and last table cells are the same, forexample, ‘1 5 1’, ‘2 3 2’.

Variables depend on your map or bookmap markup. For example, if you do not have author information inyour topicmeta/bookmeta markup, the $xmDocAuthor variable will have no effect.

Content and layout is set in the following file:

[xmfo]\Customization\fo\xsl\custom.xsl

Attributes for content styling are set in the following file:

[xmfo]\Customization\fo\attrs\custom.xsl

Table 24:Templates

DescriptionName

The header for even-numbered body pagesbody even header

The header for odd-numbered body pagesbody odd header

The footer for even-numbered body pagesbody even footer

The footer for odd-numbered body pagesbody odd footer

The header for the first body page in a part or chapterbody first header

The footer for the first body page in a part or chapterbody first footer

The header for the last body page in a part or chapterbody last header

The footer for the last body page in a part or chapterbody last footer

Table 25: Variables

DescriptionName

The title of the book$xmDocumentTitle

The subtitle or alternate title of the book$xmDocumentSubTitle

The title of the current part$xmPartTitle

The title of the current chapter$xmChapterTitle

The title of the current topic, concept or reference$xmTopicTitle

The current page number$xmPageNumber

The revision number of the book$xmDocRevision

The author of the book$xmDocAuthor

The copyright year$xmCopyRightYear

The copyright holder$xmCopyRightHolder


Footer content customization

In the code sample below, the footer for even-numbered pages has the following charac-teristics:

• The third cell (column) is eight times wider than the first and second cells ('1 1 8')

• The page number appears in the first (left) table cell

• No content in the second (center) table cell

• The document title appears in the third (right) table cell

Remember, the __body__even__footer__Cols variable sets the relative width of thefooter table cells. The value for __body__even__footer__Cols must be three integersfrom 0 to 9, separated by a space.

In the code sample below, the third column is eight times wider than the first and secondcolumns ('1 1 8')

<xsl:variable name="__body__even__footer__Cols">1 1 8</xsl:variable><xsl:variable name="__body__even__footer__col_1" select="$xmPageNumber"/><xsl:variable name="__body__even__footer__col_2">no-op</xsl:variable><xsl:variable name="__body__even__footer__col_3" select="$xmDocumentTitle"/>

Note: To have no content appear in a header or footer table cell, set the value to'no-op'

Footer style customization

The footer for even-numbered pages has red text.

<xsl:attribute-set name="__body__even__footer"> <xsl:attribute name="color">red</xsl:attribute></xsl:attribute-set>

FontsYou can set the font family and size.


DescriptionName

The base font size for the document. This is the font size that is usedby most body content (for example, paragraphs and lists). The value isset in points (pt).

xm.document.font-size

Sets the font body type for body text. Can be set to serif or sans-serif.xm.body.font.family

Sets the font type for titles. Can be set to serif or sans-serif.xm.title.font.family


Example

The base font size is set to 10 points, the body font is serif, and the title font is sans-serif.

<xsl:variable name="xm.document.font-size">10pt</xsl:variable><xsl:variable name="xm.body.font-family">Serif</xsl:variable><xsl:variable name="xm.title.font-family">Sans</xsl:variable>

TablesYou can change the table fonts, background colors, and borders.


DescriptionName

The font size for table titles.The value can be a percentageof the document.font.size value or an absolute value,in points (pt).

xm.table.title.font-size

The font size for table body content. The value can be apercentage of the document.font.size value or anabsolute value, in points.

xm.table.font-size

The background color for table headers. The value can bea color keyword (e.g., blue) or an RGB value (e.g.,#0000FF).

xm.thead.row.entry.background-color

The color of table borders. This includes the border aroundthe table, as well as any row and column borders.The valuecan be a color keyword or an RGB value.

xm.table.border.color

Turns row borders on or off. If a table in the document hasthe rowsep attribute set, then row borders are displayed

xm.table.rows

for that table regardless of the xm.table.rows value.Thevalue can be set to 1 (on) or 0 (off).

Turns column borders on or off. If a table in the documenthas the colsep attribute set, then column borders are dis-

xm.table.columns

played for that table regardless of the xm.table.columnsvalue. The value can be set to 1 (on) or 0 (off).

Example

The following table has a title font size of 14 points, a body font size of 80% of the doc-ument.font.size value, a background color specified as an RGB value, and a bordercolor of red. The row borders are displayed; column borders are not displayed.



<xsl:param name="table.title.font-size">14pt</xsl:param><xsl:param name="table.font-size">80%</xsl:param><xsl:param name="thead.row.entry.background-color">#e5e5e5</xsl:param><xsl:param name="table.border.color">red</xsl:param><xsl:param name="xm.table.rows">1</xsl:param><xsl:param name="xm.table.columns">0</xsl:param>


Glossary

A content model in a DTD is ambiguous if an element in a document instance couldmatch more than one part of the content model.

ambiguous contentmodel

A customization at the application level. Application-level customizations apply toall documents, regardless of the DTD or schema used.

applicationcustomization

A value that is associated with an element but is not part of the content of theelement. Many properties are represented by attributes, for example, class or ID.

attribute

An element whose content is preceded and followed by line breaks.block element

A program that communicates with Web servers and is used for retrieving anddisplaying documents from the World Wide Web or an intranet. Most browsers usea graphical interface to provide access to text, images, audio, and video.

browser

A widely used DTD for table markup, described in the U.S. Department of DefenseSGML standard MIL-M-28001B. XMetaL Author supports a definition of the CALSDTD developed by the OASIS consortium and described at www.oasis-open.org.

CALS table model

A way to specify document formatting that is supported by browsers. XMetaL usescascading style sheets to format the document pane in Normal and Tags On views.

cascading stylesheet (CSS)

A cascading style sheet generally consists of one or more rules that define elementappearance. These style sheets are said to be cascading because several stylesheets can be applied to the same document. See www.w3.org for more information.

One or more files that map external identifiers for DTDs, rules files, or entities to afilename. Also called OASIS catalog files. For more information on catalog files, seeOASIS Technical Resolution 9401:1997.

catalog files

Character data. A type of content in which any XML or SGML markup delimiters(such as ‘<’ and ‘&’) that appear are treated as ordinary characters. XML and SGML

CDATA

documents can contain CDATA sections; SGML documents can contain CDATAelements.

A markup construct in XML and SGML documents, beginning with the characters‘<![CDATA[’ and ending with ‘]]>’, inside which all content is treated as characterdata.

CDATA section

The way in which the content you see in XMetaL is organized in files when yougenerate output from a DITA map.You can specify chunking behaviors, for example,that split composite topics into several output files.

chunking

Component Object Model. A language-independent interface developed by Microsoftfor combining applications under Microsoft Windows.The XMetal scripting API usesa COM interface.

COM interface

An expression in a DTD that defines the content of a particular element.content model

A numerical element prefix that is incremented automatically for each successiveoccurrence of that element. For example, chapters in a document may be numbered1, 2, 3, ..., etc. Counters are implemented via a cascading style sheet.

counter

An enhancement to the functionality, behavior, or appearance of XMetaL Author.Customizations can be made at the document level or at the application level.

customization

The element containing the insertion point or selection. If an entire element isselected, the current element is the parent of that element, not the selected elementitself.

current element

XMetaL | Glossary | 189

http://www.oasis-open.org/cover/tr9502.html

http://www.w3.org/

http://www.oasis-open.org/html/a401.htm

Specifies an output format and additional configuration settings that you supply tothe DITA Open Toolkit.

deliverable type

Document type declaration. A declaration at the top of an XML or SGML documentthat specifies which DTD applies to the document, and may contain some extramarkup declarations.

DOCTYPEdeclaration

A customization that applies to all documents based on the DTD or schema usedfor the customization.

documentcustomization

The Document Object Model (DOM) is an abstract definition of an API (applicationprogram interface) for manipulating XML document structures. The DOM is a

Document ObjectModel (DOM)

Recommendation of the World Wide Web Consortium (W3C), developed andmaintained by the W3C DOM Working group. XMetaL follows the DOM Level 1Specification.The DOM was designed to represent XML structures, but can representSGML structures (such as CALS tables) if they are also found in XML.

Document Type Declaration. A set of declarations, written in a formal notation, thatdefines the structure of a document.

DTD

The building blocks of XML and SGML documents. Elements are named accordingto their function in the document, for example, headings, lists, and paragraphs.

element

An element that cannot have any content.empty element

A special character, a block of text or markup, or a file.entity

A reference, using a specific syntax, to an entity. When the document is displayedin a browser or editor, the entity reference is replaced by the text or file that theentity represents.

entity reference

A type of entity that represents another XML or SGML file.external entity

A way of identifying an external file. External identifiers can appear in a documenttype declaration and in external entity declarations, where they identify the external

external identifier

file that the entity refers to. In SGML files, external identifiers can consist of a systemidentifier, a public identifier, or both. In XML files, external identifiers must containa system identifier, which may be preceded by a public identifier.

The file, ../XMetaL/Author/extid.map, that associates external identifiers withfilenames on the system.

external identifiermap file

An element that is inserted following the occurrence of a specific element.Followed-by elements are configured in XMetaL Developer as part of thecustomization (.ctm) file.

followed-by element

A data-entry interface usually associated with specific elements in an XMetaLdocument. Forms are designed in the XMetaL Forms Toolkit (XFT) either as dialog

form

boxes that are launched from an XMetaL macro, or as content that appears as partof an element.

These can be text entities, which represent a piece of text or a single character;external entities, which represent another XML file; and graphic entities, whichrepresent a graphic, audio, or video, etc. file.

general entity

Text that is not part of the document content, but is generated by a display programand displayed at the beginning or end of an element’s content.

generated text

A type of general entity that represents an external multimedia file, for example, agraphic, video, or audio file.

graphic entity

Text that can be used to link to another document or another location in the samedocument. The viewer can display the linked document or location by clicking thetext.

hypertext

190 | XMetaL | Glossary

http://www.w3c.org/

http://www.w3.org/TR/REC-DOM-Level-1/

http://www.w3.org/TR/REC-DOM-Level-1/

A unique identifier. The value of an ID attribute must not be used for any other IDattribute in the document.

ID

An object associated with an in-place control that gives a script access to the control’sproperties, methods, and events.

IDispatch object

A reference to an ID. Unlike ID attributes, IDREF attributes do not have to be unique:more than one IDREF can refer to the same ID.

IDREF

An element that does not have a line break before or after its contents.inline element

An ActiveX control that is embedded in the Normal and Tags On document panesin XMetaL Author or XMetaL XMAX, and communicates with XMetaL Author or

in-place control

XMetaL XMAX so that changes in the control can modify the document, and viceversa.

An optional part of the document type declaration that may contain markupdeclarations.

internal subset

International Organization for Standardization.ISO

The character set for special or accented characters that is widely used in HTMLdocuments. This character set is also called ISO Latin 1. It includes charactersrequired for most western European languages.

ISO 8859-1 characterset

Local content includes the text and other elements that you enter during the authoringprocess and is stored within the element. Also known as ‘placeholder’ content.

local content

A sequence of XMetaL actions or script commands that can be run as a unit via akeyboard shortcut, a toolbar button, or a menu item. Macros can be recorded from

macro

within XMetaL Author, or created by inserting scripting code into a macro file usingXMetaL Developer.

A markup construct in SGML documents that designates the content for specialprocessing. The parameters of the marked section specify the type of processing.

marked section

The most common uses for marked sections are to cause a portion of the documentto be ignored at certain times, and to surround SGML markup constructs that youwant to be treated as text, not markup.

Keywords that determine how to process a marked section in an SGML document.The available keywords are INCLUDE (process the section normally); IGNORE (do

marked sectionparameter

not process the section); CDATA (treat elements and entity references in the contentas text, not markup); RCDATA (treat elements in the content as text, not markup);and TEMP (the section is temporary).

Special instructions or indicators in a document that specify how the enclosed contentis to be processed by an application. Element tags are an example of markup. In

markup

an XML or SGML document, the element tags specify the role of the content (heading,title, paragraph, etc.).

A macro file. An MCR file is an XML-based customization file containing XMetaLmacros, or scripts. For document-level customizations, the MCR filename is named

MCR file

according to the DTD or schema; for application-level customizations, the MCRfilename is xmetal.mcr.

The mini-template consists of a parent element and any child elements that arenecessary for the document to be valid as well as prompt text. A mini-template isinserted when there is no local content for an element with a content reference.

mini-template

A dialog box that remains active until it is closed. Once it is open, you must completeyour task and close it before you can return to the main window and continue working.

modal dialog box

A dialog box that can remain open while you are working in the main programwindow.

modeless dialog box


A feature of XML that permits documents to contain identically-named elementsdefined in more than one DTD or schema.

namespace

A declaration in a DTD that specifies a file format that can be used for filesrepresented by graphic entities. For example, if GIF files are to be used, a notationdeclaring the GIF format must be present in the DTD.

notation

Organization for the Advancement of Structured Information Standards, a consortiumdedicated to promoting structured information standards such as XML and SGML.For more information, see www.oasis-open.org.

OASIS

Specifies the file format of an output deliverable and, in the case of PDF, a printformatter.

output format

An entity that represents one or more marked section parameter keywords.parameter entity

Parsed character data. The most common form of text content in XML and SGMLdocuments. In PCDATA text, any markup, such as element start and end tags andentity references, is interpreted with its normal meanings.

PCDATA

Saving an XML or SGML file so that it is easily readable in Plain Text view by addingwhitespace, for example, by indenting lists to reflect a nested structure.

pretty-printing

Elements that are formatted to look like the HTML PRE element; that is, with allwhitespace preserved exactly as it was entered.

PRE-like elements

An instruction that is not interpreted as part of the document’s content, but ratherinterpreted by an application that is processing the file.

processinginstruction

A system-independent string that is used to represent a DTD or entity file. Part ofan external identifier.

public identifier

Replaceable character data. SGML files can have RCDATA elements and markedsections, in which any element start- or end-tags that occur are interpreted as text,but any entity references are interpreted in the normal way.

RCDATA

Content that is stored outside of the current element, either within the same file orin another file.

referenced content

An attribute that must be present in order for the document to be valid.required attribute

An element that must be present in order for the document to be valid.required element

A file on an http or Web server.remote file

An XMetaL feature that ensures that you do not break the required structure as youedit your document; it does this by allowing you to insert only valid elements. Rules

rules checking

checking is less stringent than validation in that it checks that no errors have beenmade, but does not check that the markup is complete.

An XMetaL-specific alternative to a DTD. All of the files comprising a DTD arecompiled into a single binary rules file. Rules files can be issued to XMetaL userswho are not authorized to modify the DTD.

rules file

An XML standard for defining the structure, content, and semantics of an XMLdocument.

schema

A type of text entity whose content is specific to a particular processing applicationor platform. These entities are often used to represent platform-specific characters,

SDATA entity

and codes for formatting systems (such as troff or TEX). SDATA entities are permittedonly in SGML files.

In a cascading style sheet, a selector is an expression, representing one or moreelements, that a style property can be associated with. A selector can represent an

selector


http://www.oasis-open.org

element, several elements, an element with a specific ancestor, an element in aparticular class, etc.

A group of elements that is not marked up with one of the supported table models(CALS and HTML) that can be formatted as a table.

semantic tables

Structured General Markup Language. A standard for describing the structure of adocument using markup. SGML is described by the ISO 8879 standard 1986). HTMLand XML are applications of SGML.

SGML

An SGML declaration is a file associated with a DTD that contains information aboutthe character set, markup delimiters, quantity settings, and special markup featuresthat are available in documents that use that DTD.

SGML declaration

The variable that is used to represent the folder in which XMetaL is installed.SQDIR

An XML document that an application can parse without referring to an externalDTD. A standalone document may still require a DTD in some situations, for example,if it is being edited.

standalone document

Part of an external identifier. A system identifier is generally the filename of the file(for example, a DTD or entity set) that the external identifier refers to. In XML

system identifier

documents, system identifiers are required in external identifiers, and are interpretedas URLs.

An element in an XML or SGML file begins with a start-tag (for example, <PRE>) andends with an end tag (for example, </PRE>).

tags

Toolbar file.Toolbar and menu customizations are saved in TBR files.When XMetaLAuthor loads a TBR file, it looks for the file in the user’s personal settings folder first.

TBR

If it does not find the file, it then looks for the file in the folder specified by thetbr_path variable in the XMetaL configuration file. By default, this variable is set tothe rules_path value. If it does not find the TBR file in either of these places, itlooks for it in the folder that contains the DTD or schema, if this is a folder other thanthe Rules folder.

A type of general entity that stands for one or more text characters.text entity

A set of Java and XSL processing instructions as supplied in a script file to the DITAOpen Toolkit.

transformation type

A standard for electronically encoding the characters of many of the scripts used towrite the world’s languages, as well as special symbols such as mathematical

Unicode

symbols. Unicode is the character encoding specified by XML. For more information,see www.unicode.org.

Uniform Resource Locator. A URL is the address of a file, written in a format thatcan be interpreted by a Web server.

URL

An XML or SGML document is valid if it is well-formed and if it conforms to the rulesin the DTD or XML schema.

valid document

Visual Basic Script. A scripting language implemented by Microsoft Visual Basic.VBScript is one of the languages that can be used to configure XMetaL with theCOM interface .

VBScript

World Wide Web Consortium, an industry association for the development of WorldWide Web technologies. For more information, see www.w3.org.

W3C

World Wide Web Distributed Authoring and Versioning, the Internet EngineeringTask Force standard for collaborative authoring on the Web. WebDAV is a set of

WebDAV

extensions to the Hypertext Transfer Protocol (HTTP) and Secure Hypertext TransferProtocol (HTTPS) that facilitates collaborative editing and file management betweenusers located remotely from each other on the Internet.


http://www.unicode.org/

http://www.w3.org/

An XML document that is structurally correct according to the XML standard. Thereare several aspects to well-formedness, the most important of which are: the

well-formeddocument

document must have only one top-level element, and all elements must be properlynested.

One or more space, tab, carriage return, or line feed characters, in any combination.whitespace

This is a generic term for the collection of Web servers and browsers. Usuallyabbreviated as WWW, or simply called ‘the Web’.

World Wide Web

XMetaL Application Customization file. A compiled, deployable customization file.It contains all the files created or copied during the build process, and is recognizedby XMetaL Author and XMetaL XMAX as a customization.

XAC

XMetaL Forms Toolkit. A set of form creation and form layout tools that developerscan use to design and implement embedded forms and modal dialog boxes.

XFT

Extensible Markup Language. An easy-to-implement subset of SGML, originallydesigned for displaying content over the Internet. XML is an initiative of the W3C.For more information, see www.w3.org/XML.

XML

A processing instruction that appears at the start of an XML document. Thisprocessing instruction indicates the XML version being used, and may specify thecharacter encoding and whether the document needs an external DTD.

XML declaration

Extensible Stylesheet Language: Transformations. A language for describing howto transform an XML document into another XML document.

XSLT


http://www.w3.org/XML/

Index

.dita extension, specifying in deliverable type 153

.rls/.rlx/.rld files 30

.tbr files 108

.xft 159

A

abbreviations lists, creating 141abstracts, creating 141accelerator keys 113accepting tracked changes 84Access databases 101access keys 113Acrobat Distiller 148adapter configuration file 163adding rows and columns 78alternate sorting, for index terms 128alternative text

element versus alt attribute 71in element 70, 71

ancestor elements 17, 46, 49Ant parameters 150Antenna House XSL Formatter 148Apache FOP 148appendixes, creating 141applying conditions 155args parameter 145aspect ratio 70, 71asset templates 99assets 98, 99, 100

adding objects to an asset folder 100asset templates 99Assets tab 98creating a new folder 99creating your own 99customizable asset templates 98, 99inserting in a document 99My Assets folder 99

Assets tab 98attach

content reference 135attribute declarations (Schema support) 30attribute group definition (Schema support) 30Attribute Inspector 19, 50

in Plain Text view 19tabs 50

attributes 20, 46, 49, 50, 62displaying in structure view 20editing 50finding 62removing 62searching for 62special characters 49

AttributeUses (Schema support) 30

B

back matter, creating 141bibliographies, creating 141Blank XML Document template 51, 107blue diamond (to denote empty elements) 46BMP files 72bold text

in DITA documents 124book lists, creating 141bookmap metadata 140bookmaps 140browsers

associating with buttons 27removing from Preview toolbar 27

built-in entities 38

C

CALS tables 73, 75, 76, 77cell properties 77inserting 76properties 75Proportional column widths 76

caption, HTML table 74, 75cascading style sheets

structure view 20case, names 29CDATA sections 38cells, table 73change display font size 159change list 17changes

accepting tracked 84rejecting tracked 84tracking 83

changingoptions 110

chapters, creating 141characters

converting to entities 45non-ASCII 45special 45

checkingmarkup 31

checking spelling 85, 92CHM output

customizing 165chunking 146, 147

setting 147Close 54Close All 55closing

multiple documents 55cmd_always_open_log parameter 143Collapse command 18

XMetaL | Index | 195

collapsing/expanding tags 18colophons, creating 141column properties 77comment status

XMetaL Reviewer 164comments

displaying 37filtering 164inserting 37removing 164

comments, text vs. draft-comment element 37complex type definitions (Schema support) 30components 133, 134concept topics 120condition configuration file 154conditional text 128, 154, 155

show or hide 155conditions 154, 155, 156

applying 155attributes 156changing appearance of 155configuring 156creating 154, 156defining 154, 156generating output for 154multiple 154, 155otherprops attribute 156styling 155

configuration 106configure XMetaL

for a specialization 157conref attribute 131, 134, 135

detach 135content

authoring 119, 123DITA

sample files 123DITA Language Reference 123editing 119, 123Help on current element 123re-using 131updating 132

content re-use 121content reference

attach 135detach 135insert 134previewing 134, 135

content referencesdisplaying 132editing 132generalizing element names with 133removing 132updating 132validating 132

content repository 161context area 17, 46, 49contracting cells 80copycss parameter 166copying

text 58

createabbreviations list 141abstract 141appendix 141back matter 141bibliography 141booklist 141chapter 141colophon 141dedication 141DITA bookmap 140DITA map 136draft introduction 141figures list 141front matter 141glossary 141index 141new topic 123notice 141part 141preface 141reusable component 133special topic 141table of contents 141tables list 141topic 137trademark list 141

create a templatefor a specialization 158

cross-references 125, 126insert 126

CSS filescustom 166

current element 17, 46, 49custom formatting

for a specialization 159customizable asset templates 98customizing 106customizing XMetaL Author 107, 108, 109, 110

menu commands 109menus 109submenus 109templates 107toolbar buttons 108toolbars 108

Cut 59

D

data file (thesaurus) 90database import 101, 102, 103, 104, 105

choosing databases 101choosing fields 102field properties 103filtering records 103formatting table and element output 103table joins 104updating tables 105

databases 101declaration subset 34dedications, creating 141definition lists 68

196 | XMetaL | Index

deleting rows and columns 79deliverable types 143, 144, 147, 148, 167

creating 147editing 148parameters 167XMetaL Enhanced 144

demote topic (DITA) 127Desktop tab 98detach

content reference 135diamond (to denote empty elements) 46DITA 14, 15, 73, 119, 123, 157, 158, 159

defined 119references 15sample map file 14sections 123specializations 157, 158, 159tables 73

DITA Architectural Specification 122DITA bookmaps 138, 139, 140, 141

create 140editing 138, 139, 140generated components 140insert abbreviations list 141insert abstract 141insert appendix 141insert back matter 141insert bibliography 141insert booklist 141insert chapter 141insert colophon 141insert component 140insert dedication 141insert draft introduction 141insert figures list 141insert front matter 141insert glossary 141insert index 141insert notice 141insert part 141insert preface 141insert special topic 141insert table of contents 141insert tables list 141insert trademark list 141XML view 139

DITA Configuration Save Copy as Template macro 158DITA Language Reference 122DITA maps 127, 136, 137, 138, 139, 148

element 136element versus title attribute 138create 136editing 136, 138, 139fixing validity problems 136generate output for 148insert another map 138insert Eclipse navigation reference 138insert topic 137insert topic group 137insert topic heading 138map editor 136, 138reference to non-DITA files 137

DITA maps (continued)refreshing references 127relationship tables 138XML view 136, 139

DITA Open Toolkittroubleshooting 153version 145

DITA Open Toolkit User Guide 122DITA options 111DITA_OT_NEW parameter 145DITAVAL files 155DocBook 148docked panes 20DOCTYPE 19, 33, 34, 41

internal subset 34suppressing 19

document metadata 127document publishing 143document type declaration 33document type name 33document views 17documents

moving between 55saving 53structure 31

domainshiding and showing 111

download referenced components 161draft introductions, creating 141dragging-and-dropping

text 58DSDK_PARAM_ditaext parameter 153DTD-less documents 55DTDs 30, 34, 51, 106

configuration of XMetaL 106internal 34

E

Eclipse Content 148Eclipse Help 148Eclipse navigation reference 138edit

deliverable type 148DITA bookmap 140DITA bookmaps 138, 139DITA map 136DITA maps 138, 139element properties 128image properties 128index markers 128reusable component 128table properties 128topic metadata 128

editingaccepting tracked changes 84rejecting tracked changes 84source 19, 32text 58text entities 44tracking changes 83


elementinline 124insert 124

element declarations (Schema support) 30element properties 128elements

ancestor 46, 49attributes 50current 46, 49empty 46, 49finding 62, 63inserting 46, 124replacing 62, 63selecting 58

EMF files 72empty elements 29, 46, 49empty.gif file 46, 49enlarging the document pane 21entities 38, 41, 42, 43, 44, 45, 53, 71

built-in 38changing 44converting to characters 45creating 43deleting declarations 44external 43figure 42general 41inserting 44naming conventions 41opening external 43opening external entities 53parameter 43representing images 71text 42

entity content types 42entity references 29, 44, 62, 63, 64

finding 63, 64replacing 63, 64replacing text 62replacing with text 64

EPS files 72error checking 85, 92Euro symbol 45Excel spreadsheets

importing 101pasting as tables 82

Expand 18extended publishing options

specifying parameters 150external entities 43external identifiers 29

F

figure with title 71figures 71

aspect ratio 71figures lists, creating 141file and folder naming rules 153filename

prefix 112filenames 112

filescreating from a DTD/rules file 51creating from a template 51creating new 51DTDs 30opening 51printing 57rules files 30saving 53

Find and Replace 61finding

attribute values 62elements 62, 63entity references 63, 64text 61text in an element 62using pattern matching 64

finding comments 164finding information 15floating panes 20font size, changing 159footers 166form 159Formatting toolbar 24front matter, creating 141full screen mode 21

G

general entities 41generalizing element names 133generate IDs 159generate output 146, 148, 153

chunking 146troubleshooting 153

getting started 119GIF files 72glossaries

creating 141, 142sorting 144

glossary termssorting 142, 146

graphic entities 42graphics 72

H

headers 166headings within topics 123height (images) 71Help compilers 147Help viewers 147here 118HTML Help 143, 148HTML Help Workshop 147HTML tables 73, 76, 77

cell properties 77column properties 77inserting 76properties 76row properties 77


I

ICO files 72identifier

external 33public 33system 33

IDs 111changing format 111

image properties 128images 70, 71, 72, 110

alternative text 71aspect ratio 70BMP files 72EMF files 72EPS files 72formats supported 72GIF files 72height 71hiding 110ICO files 72IMG element 71inline 110inserting 70JPG files 72PCX files 72PNG files 72represented by entities 71showing 110source file 71SVG files 72TGA files 72TIF files 72vertical alignment 71width 71WMF files 72

IMEs 35importing

databases 101Excel spreadsheets 101

index markers 128, 129creating 128page ranges 128See and See also entries 128sorting 128sub-entries 128

indexes, creating 128, 141inline element 124inline elements 124inline images 110input method editors 35insert

abbreviations list into a DITA bookmap 141abstract into a DITA bookmap 141appendix into a DITA bookmap 141back matter into a DITA bookmap 141bibliography into a DITA bookmap 141booklist into a DITA bookmap 141chapter into a DITA bookmap 141colophon into a DITA bookmap 141component into a DITA bookmap 140content reference 134

insert (continued)cross-reference 126dedication into a DITA bookmap 141definition list 68draft introduction into a DITA bookmap 141element with content reference 134elements 124figure with title 71figures list into a DITA bookmap 141front matter into a DITA bookmap 141glossary into a DITA bookmap 141headings within topics 123image 70index into a DITA bookmap 141index markers 129inline elements 124link 126list 67list item 67list of steps 125metadata 127, 140multimedia object 125notices into a DITA bookmap 141object 125part into a DITA bookmap 141preface into a DITA bookmap 141reference to a non-DITA file into a DITA map 137related link 126relationship table 138reusable component 134special topic into a DITA bookmap 141step component 125subtopic 123table of contents into a DITA bookmap 141tables list into a DITA bookmap 141task 125topic group into a DITA map 137topic into a DITA map 137trademark list into a DITA bookmap 141URL into a DITA map 137

insertingCALS tables 76comments 37elements 46HTML tables 76

inserting elements 46integrating revisions

XMetaL Reviewer 164interface

document views 17introduction 17Normal view 17Page Preview 19pane buttons 20panes 20Plain Text view 19tag tips 18Tags On view 18toolbars 23workbook mode 22workspaces 22

internal DTD 34


internal subset 34, 41ISO 8859-1 character set 35, 45ISO Latin 1 45ISO numeric characters 45italic text

in DITA documents 124

J

Java parameters 150JavaHelp 148JPG files 72

K

keyboard shortcuts 113

L

language, specifying 146languages 86, 88, 91Latin 1 character set 45limitations

wildcards 30link element 125, 126links 121, 125, 126

relationship tables 121list items 67list of steps 125lists

changing type 68converting block elements to 68converting paragraphs to 68inserting 67inserting a list in a list 67

local and active entity set 44local content 131log file 143

M

macros 78, 94, 96, 97, 109changing shortcut key 96default macro file 94defined 94deleting 97inserting a tab in a table 78loading 94locations 94macro files 94restrictions 94running 94

Macros 94Macros toolbar 26main word lists 86

adding 86removing 86

map references 138maps 121, 136

relationship tables 121See DITA maps 136

Marked Section (Insert menu) 40marked section parameters 38, 39

result parameters 39marked sections 38, 43

parameter entities 43marking revisions 83markup 17, 19, 31, 110

display options 110repairing 31source editing 19validating 31

menu commands, custom 109menus, custom 109merging cells 80metadata 127, 140mini-template 132minimization 29mnemonic 113model group definitions (Schema support) 30model groups (Schema support) 30monospaced text

in DITA documents 124moving between documents 55moving rows and columns 79multimedia object 125multiple documents 22multiple panes 20multiple-user settings 106, 108My Assets folder 99

N

names 29naming rules, for files and folders 153New 51new document 51non-ASCII characters 45Normal table 73Normal view 17notation declarations (Schema support) 30notes

in DITA documents 124notices, creating 141

O

OASIS (CALS) tables 73omitted tags 29Open 51open a DITA bookmap component 141open referenced file 141opening

documents 51external entities 53files in WebDAV-enabled folders 53remote files 51templates 51

options 110, 111auto-saving 110DITA 111File 110font 110


options (continued)General 110show/hide inline images 110syntax coloring 110tab 110tooltips 110View 110word wrap 110

otherprops attribute 154outline view 20output formats 148, 152

creating 152distributing 152modifying 152

output log 143, 153output options

for a deliverable type 145global 145local 145

output parameters 150overriding formatting

for base DITA elements 159

P

Page Preview 19page ranges, for index terms 128panes

Attribute Inspector 20, 50behavior 20buttons 20docked 20Element List 20, 46floating 20options 20Resource Manager 20, 98rules for docking and floating 20

paragraphsin DITA documents 124

parameter entities 43parameters 150Particles (Schema support) 30parts, creating 141Paste 59pasting 58pattern matching 64, 65

summary 65PCX files 72PDF 143, 148PDF output

customizing 173generate IDs for 159localizing 184special requirements in specializations 159

personal settings 95, 106, 108phrases

in DITA documents 124placeholder content 131Plain Text view 19

available commands 19PNG files 72prefaces, creating 141

prefixfilename 112

preformatted textin DITA documents 124

preview options 143Preview toolbar 26print formatters 148printing 57processing instructions 29promote topic (DITA) 127prompt text 46, 132properties

editing 128, 138Properties table 73public identifier 33PUBLIC keyword 33publishing 143, 145, 148

generate output 148output options 145preview options 143

publishing configuration files 150

Q

quotationsin DITA documents 124

quotesin DITA documents 124

R

raw code editing 19re-using content 131read-only elements 46, 49reference topics 120referenced content 131references

refresh 127refresh all references 127rejecting tracked changes 84related links 125, 126

insert 126relationship tables 121, 138remote files 51removing comments 164RenderX XEP 148repair table structure 73replacing

elements 62, 63entity references 63, 64entity references with text 64text 61, 62text with entity reference 62using pattern matching 64

repository adapter 161repository configuration file 163repository file

creating 162creating new map 162

repository integration layer 161repository map file

opening 161


Repository toolbar 162repository topic file

opening 161Resource Manager

Assets tab 98defined 98Desktop tab 98editing images 98inserting images 98inserting objects 98

restricting spell checking 85result parameters 39reusable components

create 133displaying 132edit 128editing 132inserting 134removing 132updating 132validating 132

Reviewing toolbar 28revision marking 83revision status

XMetaL Reviewer 164revisions

accepting marked 84integrating in XMetaL Reviewer 164rejecting marked 84tracking 83

Rich Text Format 148row properties 77RTF 148rules checking 31, 32rules files 30, 51Rules folder 30running

macros 94

S

sample files 14Save 54Save All 54Save As 54Save Copy as Template macro 158saving

documents 53multiple documents 54options 110validating before 53

schemasconfiguration of XMetaL 106

Schemaslimitations 30rixml support 30support for 30

screen tips 110SDATA entities 29Search options 61search patterns 64, 65

summary 65

searching 61, 62, 63, 64for attribute values 62for elements 62, 63for entity references 63, 64for text 61using pattern matching 64within an element 62

sectionsCDATA 38in DITA topics 123marked, in SGML 38

See and See also entries, for index terms 128selection methods

table cells 77settings

multiple users 106, 108personal 95, 106, 108

SGML 29, 38, 46, 49, 50attributes 50differences from XML 29empty elements 46, 49marked sections 38

short description 120shortcut keys 113, 114, 115, 116, 117, 118

choosing menu commands 117editing commands 113formatting lists 115making and extending selections 116, 117moving around in a document 115moving around in tables 116moving between panes and dialog boxes 117navigating in a dialog box 118switching views 114text and markup operations 114working with files 113

showinginline images 110

showing or hiding conditional text 155Simple table 73simple type definitions (Schema support) 30Smart Insert 124sorting, for glossary terms 144, 146sorting, for index terms 128source editing 19special characters 45Special Characters toolbar 28special topics, creating 141specialization attributes 111specializations 157specialized menus and toolbars 157specify XSL stylesheet 145spell checker 85, 86, 87, 88, 92

languages 86options 86, 87, 88, 92word lists 86, 87, 88

spell checkingrestricting 85

Split Cell into Columns 80splitting

cells 80elements 47

splitting elements 47


SQL 101Standard toolbar 23status of comments

XMetaL Reviewer 164Step choices table 73step component 125structure view 20style conditions 155sub-entries, index terms 128submenus, custom 109subscript

in DITA documents 124subtopics 123superscript

in DITA documents 124support for Schemas 30SVG files 72symbol characters 45Symbols toolbar 28system identifier 33SYSTEM keyword 33

T

Table Advanced toolbar 26table cells

contracting 80entering tab character 78height (HTML) 79merging 80properties 77properties (CALS) 77properties (HTML) 77selecting 77spanning 80splitting 80width 79

table properties 128Table Properties 76Table toolbar 25tables 73, 74, 75, 76, 77, 78, 79, 80, 82, 101, 103

adding rows and columns 78CALS

Proportional column widths 76CALS properties 75caption (HTML) 74, 75cell properties (CALS) 77cell properties (HTML) 77cells 73change body row to header row 77change header row to body row 77column properties (CALS) 77column properties (HTML) 77column/cell width 79contracting cells 80deleting rows and columns 79Editing attributes 74, 75from database 101header rows 77HTML properties 74inserting (CALS) 76inserting (HTML) 76

tables (continued)moving rows and columns 79navigating in 78pasting from other applications 82properties (HTML) 76repairing 73row properties (CALS) 77row properties (HTML) 77row/cell height (HTML) 79splitting cells 80width (HTML) 76working with HTML tables 73XML model 103

tables lists, creating 141tables of contents, creating 141tag icons 18

collapsing/expanding 18tag tips 18, 46, 49tag-valid markup 31Tags On view 18task 125task topics 120teletype text

in DITA documents 124templates 51, 107

creating 107text

finding 61finding in an element 62replacing 61, 62replacing entity references 64replacing with entity 62

text entities 42, 44editing 44

Text Processor for Typesetters 148TGA files 72thesaurus 88, 89, 90, 92

data file 90languages 88options 89, 90, 92

TIF files 72tips

in DITA documents 124toolbars 23, 24, 25, 26, 27, 28, 108, 109, 162

built-in 23custom 108custom buttons 108Formatting 24Macros 26Preview 26Repository 162Reviewing 28Special Characters 28Standard 23Symbols 28Table 25Table Advanced 26Views 27

tooltips 110topic heading in DITA map 138topic headings 138topic metadata 127, 128


topic references 138topics 120topics, creating 123, 137topics, promoting or demoting in DITA 127tracking changes 83trademark lists, creating 141transformation type 148transtype 148TROFF 148troubleshooting 153

U

underlined textin DITA documents 124

Unicode 35, 36updating content when opening files 111updating references when opening files 111URLs 137US-ASCII encoding 35user word lists 86, 87, 88

adding 87default 87entries 87, 88

User's Guide 15UTF-8, UTF-16 encodings 35

V

Validate document 32Validate Document 19, 31

in Plain Text view 19Validate selection 32validation 19, 31

document 31selection 31XML 31

vertical alignment 71View SQL tab 101viewing properties 138Views toolbar 27

W

warningsin DITA documents 124

Web links 126, 138Webdav 51WebDAV 53

file caching 53

WebDAV (continued)opening files 53

well-formed editing 55, 56adding new attributes 56adding new elements 56

well-formed markup 29, 31width (images) 71wildcards

Schema 30windows 20WMF files 72word lists 86, 87, 88

main 86user 86, 87, 88

workbook mode 22workspaces 22writing tools 85, 86, 87, 88, 89, 90, 91, 92

languages 86, 88, 91spell checker 85, 86, 87, 88, 92thesaurus 88, 89, 90, 92

WYSIWYG editing 17

X

XHTML 148XHTML output

customizing 165XMetaL Connector 161XMetaL Evaluation Guide 122XMetaL form 159XMetaL Reviewer 164

comment status 164finding comments 164integrating revisions 164removing comments 164

xmllang attribute 146

XML 15, 17, 19, 29, 31, 41, 46, 49, 50attributes 50differences from SGML 29editing 29empty elements 46, 49entities 41references 15source editing 19specification 15version 29well-formed markup 31

XML declaration 35XML table model 103xref element 125, 126

Documents

XMetaL Author 5.1 Enterprise Edition User&apos;s Guide

XMetaL Author 5.1 Enterprise Edition User's Guide