Issuu on Google+

XMetaL Author 5.1 Enterprise Edition User's Guide


Contact Information: Support: North America: +1 866 647 2003 Europe: +44 (0) 1753 607 627 Sales: North America: +1 866 793 1542 Europe: +44 (0) 1753 607 650 International: +1 604 697 8701

Office Locations: About JustSystems JustSystems is a leading global software provider with a 27-year history of successful innovation in office productivity, information management, and consumer and enterprise software. With over 2,500 customers worldwide and annual revenues over $110M, the company is continuing a global expansion strategy that includes the launch of its new enterprise software offering called xfy (pronounced 'x-fie'), and XMetaL content lifecycle solutions. JustSystems has worldwide office locations including global headquarters in Tokyo, Japan, and regional offices in New York, NY; London, UK; and Vancouver, Canada. The company currently employs over 1,000 people. Major strategic partnerships include IBM, Oracle and EMC. For more information, please visit http://na.justsystems.com. Copyright JustSystems Inc. All rights reserved. XMetaL is a registered trademark of JustSystems Canada Inc. Other product names may be trademarks or registered trademarks of their respective owners. XMetaL Author 5.1 Enterprise Edition 12/2007

XMetaL Sales & Support Suite 1800, Two Bentall Centre 555 Burrard Street Box 207 Vancouver, BC, Canada V7X 1M9 T: 604-602-9928 F: 604-602-9938 Toll-Free Sales: 1-866-793-1542 European Headquarters Regus House, 268 Bath Road Slough SL1 4DX, United Kingdom T: +44 (0) 1753 607 650 F: +44 (0) 1753 708 625 US Office 1450 Broadway, 39th Floor New York, NY 10018 USA Toll-Free: 1-866-JSI-4-XML Tokushima Head Office Brains Park Kawauchi-cho Tokushima-city Tokushima 771-0189 Japan T: 088 666 1000 (+81 88 666 1000 from outside Japan)


XMetaL | Contents | 3

Contents Welcome to XMetaL Author.................................................................................13 Sample files...........................................................................................................14 Finding information..............................................................................................15 Introduction 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


4 | XMetaL | Contents

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.........................................................................................46 Inserting 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


XMetaL | Contents | 5

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

Working with files.................................................................................................51 Creating 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....................................................................................58 Selecting text..........................................................................................................................58 Editing selections...................................................................................................................59 Copy and paste a selection....................................................................................................59 Move a selection.....................................................................................................................59 Delete a selection...................................................................................................................60

Finding and replacing text...................................................................................61 Searching 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


6 | XMetaL | Contents

Find and replace an entity reference with text.............................................................64 Using search patterns............................................................................................................64 Search pattern summary........................................................................................................65

Working with lists.................................................................................................67 Insert 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............................................................................................70 Insert 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..............................................................................................73 HTML 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


XMetaL | Contents | 7

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.......................................................................................83 Track changes........................................................................................................................83 Move between tracked changes.............................................................................................84 Accepting or rejecting tracked changes..................................................................................84 Accept or reject tracked changes...........................................................................................84

Using the writing tools.........................................................................................85 Checking 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........................................................................................................94 Restrictions on macros...........................................................................................................94 Running macros.....................................................................................................................94 Run a macro...........................................................................................................................95


8 | XMetaL | Contents

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..............................................................................98 Assets 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..........................................................................................101 Import 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..............................................................................106 Customizing 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


XMetaL | Contents | 9

Setting options......................................................................................................................110 Setting DITA options.............................................................................................................111 Setting a filename prefix.......................................................................................................112

Keyboard shortcuts............................................................................................113 File 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...........................................................................................119 Topics...................................................................................................................................119 Topic structure......................................................................................................................120 Maps.....................................................................................................................................121 Relationship tables...............................................................................................................121 DITA references....................................................................................................................122

Authoring DITA content......................................................................................123 Create 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................................................................................................131 Displaying reusable content.................................................................................................132 Generalizing elements with content references....................................................................133


10 | XMetaL | Contents

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....................................................................................136 Create 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...........................................................................140 Create 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.......................................................................................143 XMetaL 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


XMetaL | Contents | 11

Create an output format.............................................................................................152 Modify an output format.............................................................................................152 Troubleshooting....................................................................................................................153

Working with conditions....................................................................................154 Apply a condition..................................................................................................................155 Display conditions in previews or output..............................................................................155 Style a condition...................................................................................................................155 Modify conditions..................................................................................................................156

Working with DITA specializations....................................................................157 Configure 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....................................................................161 Open 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......................................................164 Find comments.....................................................................................................................164 Filter comments....................................................................................................................164 Integrate revisions................................................................................................................164 Change comment status......................................................................................................164 Remove all comments..........................................................................................................164

Appendix A: Configuring XHTML and CHM output.........................................165 Creating 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...............................................................173 Custom 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


12 | XMetaL | Contents

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


XMetaL | Welcome to XMetaL Author | 13

Welcome to XMetaL Author XMetaL Author is a graphical editor for creating and editing XML and SGML documents. It provides authors with a familiar word processing environment and a rich array of powerful authoring aids including multiple document 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 find that 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 docs-feedback@xmetal.com.


14 | XMetaL | Sample files

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.


XMetaL | Finding information | 15

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 by clearing the Show Tips on Startup option. You can display a tip at any time by choosing Tip of the Day from the 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 listed below. • The Extensible Markup Language (XML) 1.0 (Fourth Edition) (a W3C Recommendation), available at www.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 at www.w3.org/XML • XML.com • The SGML/XML Web Page (maintained by Robin Cover) at www.oasis-open.org/cover/sgml-xml.html provides a 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 also www.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 on various 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 advanced webmasters 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 IBM developerWorks 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.vrcommunications.com/resources.htm • xmetal-dita and dita-users user groups on yahoo.com


16 | XMetaL | Finding information

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


XMetaL | Introduction to the user interface | 17

Introduction to the user interface The XMetaL Author interface is highly customizable. This topic, and this online help in general, explain the interface and default (non-customized) functionality. The version you are using may differ because of customization. If XMetaL Author has been customized at your site, there may be a person responsible for customization 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 Element List 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 to work 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 Sheet controls the formatting. For example, headings can be larger than body text, certain kinds of text can be bold 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 images and tables. Structured editing commands are available from the menus; you need not be concerned about the 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 the Normal view. Because these customizations are site-specific, the exact capabilities of Normal view editing


18 | XMetaL | Introduction to the user interface

vary. If the Normal view is properly configured, it is easy and convenient to edit documents in this view. Some editing 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 element could insert a paragraph element. • If the selection or insertion point is inside a sequence of nested block elements, pressing Enter repeatedly moves 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 when the 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 line break, 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 On view is useful for navigating the element hierarchy and for accurate positioning of the insertion point. The complete 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 5. In the Color to Use area, specify a color value.

and type a name.


XMetaL | Introduction to the user interface | 19

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, the DOCTYPE declaration is visible at the top of the file. This declaration specifies a DTD, a file that describes the allowable sequences of elements and attributes. Since context-sensitive rules checking is not active in Plain Text view, XMetaL Author does not prevent you from entering invalid markup. However, you can still validate your document. To differentiate between the different types of markup, Plain Text view is color-coded.The markup is organized and 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 current width 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 of selected 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 to Normal or Tags On view.

Page Preview In Page Preview, you can display XML documents as they would appear in a Web browser. You can perform any browser tasks, including navigating to links. By right-clicking your document, you can bring up a menu from 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 that style sheet. Tip: You can also preview a document and add or delete a browser by choosing File ➤ Preview in Browser.

Select a view 1. Click View and select one of the following: • • • •

Normal Tags On Plain Text Page Preview


20 | XMetaL | Introduction to the user interface

Using the Structure view The Structure view displays the outline or information hierarchy of the document. Block elements are displayed one 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 each DTD 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 the structure 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 corner of 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, cascading style sheets, scripts, etc., and lets you perform “intelligent insertion” of these objects. Docked and floating panes


XMetaL | Introduction to the user interface | 21

XMetaL Author panes can be customized and moved. When you first display a pane such as the Attribute Inspector, it is docked (attached) to the work area border. If you want to turn the pane into a floating pane that 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). 3. Do one of the following: • • •

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 and the Resource Manager can also be made visible in full screen mode since it has its own workspace. The fullscreen 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.


22 | XMetaL | Introduction to the user interface

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 bottom of 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, which panes and toolbars are visible, whether panes are floating or docked, and pane positions. When you save a a workspace, this current-state information is saved. The most recently saved workspace is opened the next time you start XMetaL Author. Workspace information is saved on a user-by-user basis and is saved to the Windows registry.

Create a workspace You can save a maximum of eight workspaces. If you try to save a ninth workspace, the oldest workspace is 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.


XMetaL | Introduction to the user interface | 23

Toolbars You can access commands by clicking the buttons on the toolbars. Tooltips (short descriptions of what the toolbar 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 modify existing toolbars.

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

Name/Tooltip

Keyboard shortcut

Menu command

Description

New Page

Ctrl + N

File ➤ New

Opens the New dialog box or opens a new document based on the default template.

Open

Ctrl + O

File ➤ Open

Opens the Open dialog box, from which you can open an existing document.

Save

Ctrl + S

File ➤ Save

Saves the active document.

Save All

Ctrl + Q

File ➤ Save All

Saves all open documents.

Find and Replace

Ctrl + F

Edit ➤ Find and Replace

Opens the Find and Replace dialog box.

Find Next

F3

Edit ➤ Find Next

Finds the next occurrence of the text string in the Find field of the Find and Replace dialog box.

Check Spelling

F7

Tools ➤ Spell Checker

Opens the Writing Tools dialog box to the Spell Checker page.

Cut

Ctrl + X

Edit ➤ Cut

Removes the selected text or element(s) to the Windows clipboard.

Copy

Ctrl + C

Edit ➤ Copy

Copies the selected text or element(s) to the Windows clipboard.

Paste

Ctrl + V

Edit ➤ Paste

Pastes the contents of the clipboard.

Undo

Ctrl + Z

Edit ➤ Undo

Reverses the last action.

Redo

Ctrl + Y

Edit ➤ Redo

Redoes the last reversed action.


24 | XMetaL | Introduction to the user interface

Insert Image

-

Insert ➤ Image

Inserts an image element.

Insert Table

-

Table ➤ Insert Table

Inserts a table element and all required child elements.

Insert ➤ Element

Opens the Element List.

View ➤ Resource Manager

Opens or closes the Resource Manager pane (toggle action).

Insert Element

Ctrl + Shift + I

Resource Manager

-

Previous Document

Alt + Left Arrow

Window ➤ Previous

Makes the previous document in the list of open documents the active document.

Next Document

Alt + Right Arrow

Window ➤ Next

Makes the next document in the list of open documents the active document.

Validate Document

F9

Tools ➤ Validate Document

Checks the active document for wellformedness and validity.

Help Contents

F1

Help ➤ Contents

Opens the XMetaL Author online Help.

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

Name/Tooltip

Keyboard Shortcut

Description

Lists the elements that can be inserted at the cursor location.

Style Element

Bold

Ctrl + B

Applies or inserts an element designated as bold.

Italics

Ctrl + I

Applies or inserts an element designated as italic.

Underscore

Ctrl + U

Applies or inserts an element designated as underscore.

Numbered List

Inserts an element designated as an ordered (numbered) list.

Bulleted List

Inserts an element designated as an unordered (bulleted) list.


XMetaL | Introduction to the user interface | 25

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

Name/Tooltip

Menu command

Description

Insert Table

Table ➤ Insert Table

Opens the Insert Table dialog box.

Edit Table Properties

Table ➤ Table Properties

Opens the Table Properties dialog box.

Insert Row Above

Table ➤ Insert Rows or Columns

Adds an empty row above the current row.

Insert Row Below

Adds an empty row below the current row.

Delete Row

Table ➤ Delete Row

Deletes the current row, including any elements and text in the row.

Insert Column Left

Table ➤ Insert Rows or Columns

Adds an empty column to the left of the current column.

Insert Column Right

Adds an empty column to the right of the current column.

Delete Column

Table ➤ Delete Column

Deletes the current column, including any elements and text in the column.

Move Row Up

Table ➤ Move Row or Column

Moves the current row up one row.

Move Row Down

Moves the current row down one row.

Move Column Left

Moves the current column to the left by one column.

Move Column Right

Moves the current column to the right by one column.

Merge Cell Right

Table ➤ Merge Cell

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

Merge Cell Left

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

Merge Cell Up

Merges the current cell with the cell above it.

Merge Cell Down

Merges the current cell with the cell below it.

Split Cell into Rows

Table ➤ Split Cell into Rows

Splits the current cell into two cells horizontally.

Split Cell into Columns

Table ➤ Split Cell into Columns

Splits the current cell into two cells vertically.


26 | XMetaL | Introduction to the user interface

Table Advanced toolbar The Table Advanced buttons are only available when the cursor is located in a table cell that spans at least two rows, at least two columns, or both. Note: Your installation of XMetaL Author might not include all of these buttons. It might also include buttons not listed here. See your customizer for more information. Button Icon

Name/Tooltip

Description

Contract Cell from Left

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

Contract Cell from Right

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

Contract Cell from Bottom

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

Contract Cell from Top

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

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

Name/Tooltip

Menu command

Description

Tools ➤ Macros to open the Macros dialog box. (You can perform both of these functions from the Macros dialog box.)

Runs the macro selected in the Select Current Macro list.

Record Macro

Tools ➤ Record New Macro

Records all keystrokes as a new macro.

Stop Recording

Tools ➤ Stop Recording

Stops recording keystrokes to the new macro.

Macros

Tools ➤ Macros

Opens the Macros dialog box.

Run Current Macro Select Current Macro

Shows the currently selected macro. Click the arrow button to select a new macro from the list.

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


XMetaL | Introduction to the user interface | 27

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 Preview on 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 Note: Your installation of XMetaL Author might not include all of these buttons. It might also include buttons not listed here. See your customizer for more information. Button Icon

Name/Tooltip

Keyboard shortcut

Menu command

Description

Plain Text

Ctrl + Shift + H

View ➤ Plain Text

Displays the active document in Plain Text view.

Tags On

Ctrl + Shift + O

View ➤ Tags On

Displays the active document in Tags On view.

Normal

Ctrl + Shift + W

View ➤ Normal

Displays the active document in Normal view.

Browse

Ctrl + Shift + V

View ➤ Page Preview Displays the active document in a browser.

Attribute Inspector

Shift + F6

View ➤ Attribute Inspector

Opens and closes the Attribute Inspector.

Insert Element Window

-

View ➤ Element List Opens and closes the Element List.

Resource Manager

-

View ➤ Resource Manager

Opens and closes the Resource Manager (toggle action).

Full screen

-

View ➤ Full Screen

Toggles between displaying the active document in full screen mode and in normal window mode.


28 | XMetaL | Introduction to the user interface

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

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

Name/Tooltip Track Changes

Menu command Tools ➤ Track Changes

Description Turns change tracking on or off (toggle action).

Previous Change

-

Goes to and selects the previous tracked change in the document.

Next Change

-

Goes to and selects the next tracked change in the document.

Accept Change

-

Accepts the currently selected change.

Reject Change

-

Rejects the currently selected change.

Accept or Reject Changes

Tools ➤ Accept or Reject Changes

Opens the Accept or Reject Changes dialog box.

Revision Mark Options

Tools ➤ Options, click the Change Tracking tab

Shows the Revision Mark Options tab.


XMetaL | Working with XML and SGML | 29

Working with XML and SGML This set of topics introduces XML and SGML, discusses some of the differences between the two, and describes 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 or SGML. But the more you work with your documents, the more likely you are to want to add something that requires some knowledge of these standards. SGML (Standardized General Markup Language) is a document processing standard defined by the World Wide Web Consortium (W3C). XML (Extensible Markup Language) is a form of SGML. Like HTML, both SGML and XML are used to “mark up” documents for structure and format. XML and SGML are much more flexible than HTML, however, because with them, you can create and format your own markup according to your needs. This makes them much more powerful tools than HTML, especially for complex document types and 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 the file is an XML file: <?xml version="1.0"?> • Empty elements in XML are marked up in the form <TAGNAME/>, whereas empty elements in SGML are marked 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 with XMetaL Author are well-formed and normalized. The structure of an XML document is determined by a DTD or Schema, which specifies which elements the XML document can (and, for some elements, must) contain, along with the ways that the elements can be combined. A Schema is always a separate file with an extension of .xsd; a DTD is often a separate file with an extension of .dtd, but simple DTDs can be included in the XML document itself as part of the DOCTYPE declaration.


30 | XMetaL | Working with XML and SGML

DTDs, Schemas, and rules files Although XML files can exist as well-formed stand-alone documents, most XML documents that you edit in XMetaL Author are associated with either a document type definition (DTD) or an XML Schema. Every SGML file 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 defined in 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 documents without having to rely on a separate DTD. Schemas also expedite the exchange of information with common 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 On view. • Checking an XML Schema (.xsd file) for errors is limited in XMetaL Author. It is recommended that you use third-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 controls are 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>


XMetaL | Working with XML and SGML | 31

</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. A rules 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 .rld file extension. Note: Typically, any DTD, rules file, or Schema that you need to use when working with XMetaL Author will 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 documents can 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 several aspects 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 tag must 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 XMetaL Author 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 document without an associated DTD. When you are working with a document linked to a DTD or a Schema, XMetaL Author ensures that you do not 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 not break the required structure as you edit your document. As well, when you open a document or switch from Plain Text view to Tags On or Normal view, XMetaL Author performs certain checks on the markup. Rules checking is less stringent than validation in that it checks that no errors have been made, but does not check that the markup is complete. For example, rules checking does not check required elements, undeclared entities, or missing ID values.


32 | XMetaL | Working with XML and SGML

Note: Rules checking and validation do not apply to well-formed XML documents that are edited without a 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 menu are 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 element from 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. For example, if a Paste operation would leave the document incorrectly tagged, a warning pops up asking if you 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 the following 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, doubleclick 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 checking does 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 cause invalid 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 turn rules checking back on by switching to Normal or Tags On view. Note: Working in Plain Text view is recommended for advanced users only.


XMetaL | Working with XML and SGML | 33

DOCTYPE declarations An XML or SGML document should start with a Document Type Declaration (DOCTYPE). The DOCTYPE declaration associates the document with a DTD or rules file by means of an external identifier. Here is an example 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 DTD or rules file. However, as you are editing a document, XMetaL Author changes this to the current top-level element in the document. External identifiers An external identifier consists of the keyword SYSTEM or PUBLIC, followed by a system identifier or a public identifier followed by a system identifer. If the external identifier starts with SYSTEM, it has only a system identifier; if it starts with PUBLIC, it has a public identifier followed by a system identifier. The system identifier can be a filename or URL. Each identifier consists of a string of characters inside double quotes. The system identifier is generally the filename of the DTD or rules file. The public identifier is an arbitrary identifier that is usually agreed upon by the various organizations that use the DTD. Some DTDs that are used by a large number of organizations have a standard public identifier. Here are two DOCTYPEs, one with a PUBLIC keyword and one with a SYSTEM keyword, that could be used to refer to the same DTD in either XML or SGML documents: â&#x20AC;˘ <!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 second identifier 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. â&#x20AC;˘ <!DOCTYPE BOOK SYSTEM "book.dtd"> The keyword SYSTEM indicates that the identifier that follows it is the system identifier. If the external identifier starts with SYSTEM, there cannot be a public identifier. This DOCTYPE refers to a DTD that has the system identifier book.dtd. The name after the word DOCTYPE is (usually) the name of the top-level element in the rules file; in these examples, that element is BOOK. There is a third possibility for SGML documents only:


34 | XMetaL | Working with XML and SGML

â&#x20AC;˘ <!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, there is no system identifier. (DOCTYPE declarations in XML documents must include a system identifer.) This DOCTYPE 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 they override any external declarations of the same attribute or entity. Duplicate ELEMENT declarations are not allowed and result in an error message. ATTLIST declarations specifying different attributes of the same element are combined, but if the same attribute is specified in both places, the specification in the internal subset takes precedence. A DOCTYPE declaration can omit the external identifier, so that the document's DTD is internal (contained completely 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 declarations are placed in the internal subset. However, note that if the internal subset contains any declarations other than ENTITY declarations, it is read-only in Tags On and Normal views, and the entity-creation commands are unavailable.


XMetaL | Working with XML and SGML | 35

Character encoding and Unicode support In XMetaL Author, you can edit and save XML and SGML documents that use US-ASCII, ISO-8859-1 (Latin1), 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 configured to use them, Unicode characters are displayed in the document pane. If a character appears as a box, then the font in use does not contain that character. The character will appear correctly when an appropriate font is used. You can enter Unicode characters using standard input devices (such as a keyboard), or IMEs (input method editors) on Windows 2000 NT 4.0 (with SP6a) and XP. You may also copy and paste characters from other tools such as the Character Map. XMetaL Author determines file encoding by checking the following conditions, in the order specified, until an encoding 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 in Appendix F of the XML specification (www.w3.org/TR/REC-xml#sec-guessing) to determine whether or not the file is in UTF-16 format (it reads the characters <? in the XML declaration and infers the character encoding 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. These encoding strings are not case-sensitive. Encoding Type

Accepted Encoding Strings

US-ASCII

ANSI_X3.4-1968 ANSI_X3.4-1986 ASCII CP367 CSASCII IBM367 ISO_646.IRV:1991 ISO646-US ISO-IR-6 US US-ASCII


36 | XMetaL | Working with XML and SGML

Encoding Type

Accepted Encoding Strings

ISO-8859-1

CP819 CSISOLATIN1 IBM819 ISO-8859-1 ISO_8859-1 ISO_8859-1:1987 ISO-IR-100 LATIN1 L1

UTF-8

UTF-8

UTF-16

UTF-16

If the XML declaration in your document contains an encoding string not listed in the above table, an error message appears and the file is opened in Plain Text view. Plain Text view assumes ISO-8859-1 character encoding. 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 (â&#x20AC;&#x153;round-trippingâ&#x20AC;?). 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 following rules, 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/entity table (charentmap.xml), and if your operating system and version of XMetaL Author is capable of displaying the 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.


XMetaL | Working with XML and SGML | 37

3. If the character/entity table (charentmap.xml) has an entity reference corresponding to the character, the character 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 ASCII and Latin-1 encodings, non-ASCII or non-Latin-1 characters are saved as entity references if they are in the character/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 if they are mapped to characters in the character/entity table (charentmap.xml), and if your operating system and 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 following rules, which are applied in the order shown: 1. If the character/entity table (charentmap.xml) has an entity reference corresponding to the character, the character 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 comments You can add text comments to your document using the Comment command. If you are working in a DITA document, you can also add a <draft-comment> element. Text comments (that you enter using the Comment command) are not displayed by browsers, but can be viewed 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 can control the display of this type of comment through the Advanced tab in the Configure Output Options dialog.

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. 2. Do one of the following: • •

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

3. Type your comment inside the tags.


38 | XMetaL | Working with XML and SGML

CDATA sections If the text of your XML or SGML document contains markup characters (<, >, or &), and you do not want to interpret these characters as markup, you can surround them with CDATA sections. Doing so enables you to 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 equivalent built-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 section and probably causes a markup error.

Insert a CDATA section 1. Do one of the following: • •

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 CDATA sections, 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 or ignored by the application that is reading the document. For example, a workbook could be printed in two versions: one for teachers that includes both questions and answers, and another for students that has only the questions. A single SGML document could be used for both versions. In this document, the answers are in 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 fragments of “raw SGML” in your document and not have them interpreted as markup. Like elements, marked sections start and end with tag icons, the marked section are displayed inside the start-tag. More.

. The result parameters of

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


XMetaL | Working with XML and SGML | 39

INCLUDE

IGNORE

TEMP

CDATA

RCDATA

The contents of the marked section should be read by the application. This parameter is the default, and is considered to be selected unless you select the IGNORE parameter. The contents of the marked section should be ignored by the application. The application should behave as if the contents of the marked section were not present in the document. Selecting (checking) the Ignore Contents check box chooses IGNORE. Temporary: you can choose this parameter if the marked section contains material that is likely to be removed later, for example, a formatting instruction inserted for a particular print run. This parameter makes it easier to locate and remove such sections. TEMP is just a label and does not, by itself, cause any special processing. Selecting (checking) the Mark as Temporary check box selects TEMP. The marked section can contain only character data (CDATA). This means that the marked section cannot contain any elements or entities: XMetaL Author does not allow you to use menu commands to enter an element or an entity reference. If the marked section contains a tag or entity that is entered as ordinary text, XMetaL Author or any another application treats it as text rather than markup. Choosing Text only (CDATA) from the Special Contents list selects CDATA. The marked section can contain only replaceable character data (RCDATA). Different from CDATA, this means that the marked section cannot contain any elements, but can contain entities. XMetaL Author does not allow you to enter an element using Element. If the marked section contains a tag that is entered as ordinary text, XMetaL Author or any another application treats it as text rather than markup. Choosing Text and Entities (RCDATA) from the Special Contents list selects RCDATA.

Result parameters You can choose marked section parameters in any combination. Some of them override others, so XMetaL Author evaluates all parameters to arrive at the result. In Tags On view, these appear at the bottom of the Marked Section dialog box with the label RESULT PARAMETERS, and inside the marked section icon. The result 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 INCLUDE is one of the result parameters. However, since it is the default, it is not displayed in the dialog box unless it is the only parameter. Because of these rules, there are actually only eight possible sets of result parameters: • IGNORE • IGNORE TEMP


40 | XMetaL | Working with XML and SGML

• 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 parameters may not be permitted for that selection: • A selection that contains start and end tag icons cannot be surrounded by a marked section that has the result parameters CDATA or RCDATA. • A selection that contains an entity icon cannot be surrounded by a marked section that has the result parameter 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 you have typed in a start-tag, for example, you are allowed surround it with a marked section containing one of the 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 look like this:


XMetaL | Working with XML and SGML | 41

Entities and special characters You can use an entity to include text or other content in an XML or SGML document by substituting a short reference 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 phrases of “boilerplate text” (text that you use frequently). You type the text only once, when you are creating the text entity, give it a name to use as the entity reference, and then insert the entity reference in the document wherever the text should appear. Text entities are also useful for words, names, or phrases that are used throughout 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 text throughout 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 document 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 and accented letters, not normally found on US keyboards. These entities are called character references. For example, the character reference &#x2026; 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 specification. Note: You can also use named character entities, for example, &hellip;, but these must be defined in your 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 unless you are indicating a namespace. • In SGML files, names cannot be longer than 128 characters. There is no such limitation for entity names in XML files. • A document cannot have more than one entity with the same name, even if they are different types of entities. However, entity names are case-sensitive. For example, ProdName and Prodname are considered to 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 name in the document, but XMetaL Author displays a warning to make sure you are aware of the other entity. The entity in the document overrides the one in the rules file.


42 | XMetaL | Working with XML and SGML

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 ( entity’s replacement text (the content) in Normal view.

, for example) in Tags On view, and as the

The default content type parameter for text entities is CDATA. If you are working with an SGML document and you want your text entity to contain some other type of text, you must switch to Plain Text view, find the entity declaration within the DOCTYPE declaration at the top of the document, and replace the parameter CDATA 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 more of the characters used in SGML markup, such as “&” or “<”. For example, an entity whose content is the phrase “R&D” should be defined as character data, otherwise “&D” will be interpreted as a reference to an entity “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 systemspecific 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 formatting instruction. 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 need include 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 entities in your document.


XMetaL | Working with XML and SGML | 43

Graphic entities are normally displayed as rectangular icons (for example, views.

) in Tags On and Normal

Graphic entities have the following content types: • Notation. The graphic entity consists of non-SGML characters. Almost all graphic entities will be of this type. • 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 and remove 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 open the 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 the current 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 marked section parameters.

Create an entity 1. Do one of the following: • • • •

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. 3. Do one of the following: • • •

For text entities, type the text content. This is the text that will appear in your document when you insert the 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.

5. Do one of the following: •

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


44 | XMetaL | Working with XML and SGML

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

6. Click New.

Change an entity 1. Do one of the following: • • • •

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

2. Click the entity whose contents you want to modify. 3. Make the desired changes. 4. Click Change.

Delete an entity 1. Do one of the following: • • • •

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

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 SGML document by inserting an entity reference. In XMetaL Author, you can insert an entity reference in your document 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 the Document entity set. The other entity sets contain entities declared in the DTD (Rules File) entity set and any external files that are referenced in the DTD.

Insert an entity reference When 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. 3. 4. 5.

Click Insert ➤ Entity Reference. From the Entity Set list, select the entity set that contains the entity you want to insert. Select the entity you want to insert in your document. Click Insert.


XMetaL | Working with XML and SGML | 45

Typing special characters and symbols The Special Characters toolbar and the Symbols toolbar allow for easy entry of special characters (uppercase and 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 have been declared. For example, the “less-than” symbol (<) is converted to the entity reference &lt;.The characters are displayed as the characters themselves in Tags On and Normal views. In Plain Text view, they appear as entity references. Note: If your document’s encoding supports the character, the character, not the character entity, is saved. Euro symbol The character entity reference for the Euro symbol is &#x20AC;. This symbol is also available from the Symbols toolbar.

Enter a special character or symbol 1. Do one of the following: • •

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 ISO Latin 1 (ISO8859-1) or ISO Numeric character set, it is converted to the equivalent character when you open the 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 ISO Latin 1 or ISO Numeric character sets) are converted to the equivalent entity or character reference.


46 | XMetaL | Working with elements

Working with elements Elements are usually named according to their function in the document. For example, <section> describes a section, <title> describes a title. An element can contain text, attributes, or other elements. The document’s DTD 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 and Tags On views, the context bar to the left of the horizontal scrollbar displays the current element preceded by its ancestors. Various operations, such as changing the element type and editing attributes, apply to the current element. Note: If you select an entire element, the current element is not the selected element. In this case, the parent of 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

as <TAGNAME> in Plain Text view, and

in Tags On view. An SGML element appears in Tags On view. Empty elements are also

designated by the icon in Normal and Tags On views. Empty elements are often used to reference images. • 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 prefer to think of elements as standing for parts of the document’s structure (for example, heading, paragraph, list item) without thinking explicitly about how they are formatted. On the other hand, if you are accustomed to working with desktop publishing or word processing applications, you may want to think of the elements as styles. XMetaL Author supports both approaches to markup. Working in Normal view is similar to applying word processing 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 tab contains 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.


XMetaL | Working with elements | 47

In some circumstances, when you insert an element, XMetaL Author automatically inserts prompt text and child 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 paragraph 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. 2. Do one of the following: • • •

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. 2. Do one of the following: • •

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 sometimes not. If there is content in the element, the first element contains all the content before the insertion point and the second element contains the remaining content. If the insertion point is just after the start tag, or just before the end tag, a new, empty element is created.

Split an element 1. Position the insertion point where you want to split the element. 2. Do one of the following: • •

Click Edit ➤ Split Element. Press Enter.


48 | XMetaL | Working with elements

Join two adjacent elements 1. Do one of the following: • • •

In Tags On view, place the insertion point just after the start tag for the second element and press Backspace In Tags On view, place the insertion point just before the closing tag for the first element and press Delete 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, combined element.

Remove elements 1. Do one of the following: • • •

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 tags You can remove the tags surrounding an element and place its content directly inside the parent element. 1. Do one of the following: • •

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


XMetaL | Working with attributes | 49

Working with attributes Attributes consist of name/value pairs and are used to provide more information about an element. The document’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 in quotation marks. For example, the element <section audience="advanced"> is designated as containing information 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 the insertion 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 document pane. In Normal view, tag tips display the attributes of images. Special characters in attribute values The following characters must be escaped. <

&lt;

>

&gt;

"

&quot;

'

&apos;

&

&amp;

Special attribute types • Required attributes. A required attribute is one that must be given a value, or else the file is not valid. The names 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 the document. When the document is validated, XMetaL Author checks that the identifier is unique, and that it contains the correct kind of characters (by default, an identifier must start with a letter, and contain only letters, numbers, hyphens, and periods). IDREFs refer to IDs. The value of an IDREF attribute must be the value of an ID attribute somewhere in the

document. When the document is validated, XMetaL Author checks that the corresponding ID attribute exists in the document. Unlike ID attributes, IDREF attributes do not have to be unique: more than one IDREF 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.


50 | XMetaL | Working with attributes

• Name token groups. A DTD can restrict the possible values of an attribute to a finite list, called a name token 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 called FIXED attributes and are displayed in grey text in the Attribute Inspector. Their values cannot be modified.

Edit an attribute You 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 want to edit. This list contains the current element and all of the elements that enclose it (Normal and Tags On views only). You can use this list to edit attributes of an ancestor of the current element. 4. Click the attribute you want to edit. 5. Do one of the following: • •

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.


XMetaL | Working with files | 51

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 rules file. 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 document When you create a blank SGML or XML document, a dialog appears asking you to choose a DTD, Schema, or rules file. 1. Click File ➤ New. 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 dragging and dropping them from another application (such as Windows Explorer) onto the background of the XMetaL Author work area. XMetaL Author determines whether to edit the file as an XML or SGML file by testing the following conditions in 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, it is 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 XML declaration to the document.


52 | XMetaL | Working with files

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 already open and in use by another user cannot be opened for editing. In this case, XMetaL Author alerts you that the 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 or maintain these privileges. Note: Internet Information Server (IIS) Version 5.0 must be installed, and the folder containing the target files 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 the horizontal 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 the DOCTYPE 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, or rules file. If you choose the correct rules file, DTD, or schema, the document opens and you can edit it in the normal way. • Edit as a partial document. (Not applicable to XML files based on schemas.) Enable this option to open the document as a well-formed document in your default editing view (Normal or Tags On). You can edit elements and attributes, but no validation takes place.


XMetaL | Working with files | 53

â&#x20AC;˘ Edit the file in plain text view. Enable this option to open the document in Plain Text view, so that no rules checking 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 not need 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 XMetaL customization for assistance.

Opening files in WebDAV-enabled folders When you open a document located in a WebDAV folder, the document is automatically locked. This means that 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 for editing by others. If you try to open a document from XMetaL Author that is in a WebDAV-enabled folder and has already been opened, 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 WebDAV server following the normal search rules. Catalogs are not downloaded from a WebDAV server; only your local 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:\Documents and Settings\<username>\Local Settings\Temp). When you open a file from a WebDAV server, the URL to this local path is mapped, and the cached file is used. If the file in the cache does not exist, the file is first retrieved from the WebDAV folder and placed there. After the document is closed, all the cached items used by the document are removed.

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

Saving documents You can save a document using its current name and folder location, save a document under a different name 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.


54 | XMetaL | Working with files

XMetaL Author automatically validates the document before saving it. If validation errors are found, a Validation Log 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 option of 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 creating new documents, the Save As dialog box prompts you to name each file sequentially. If the documents are existing documents, they are all saved without any prompting.

Save a document 1. Click File ➤ Save. 2. Do one of the following: • •

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. 2. 3. 4. 5.

Click File ➤ Save As. Navigate to the folder in which you want to save the document. Type a name for the document in the File name box. Click Save. Do one of the following: • •

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 file extension 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. 2. Do one of the following: • •

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.


XMetaL | Working with files | 55

If changes have been made to the document and not saved, a confirmation dialog box appears asking if you want to save the document. 2. Do one of the following: • • •

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 each document with changes asking if you want to save the document. 2. Do one of the following: • • •

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 documents in a variety of ways.

Move between documents 1. Do one of the following: • • • •

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 option of 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 the document. If you choose such a DTD or rules file, XMetaL Author adds a processing instruction to your document that points to it. Any elements and attributes specified in the DTD are available to the document, but because the document is not officially based on the DTD, no rules checking or validation of the document occurs. All attributes are of type CDATA, that is, they can contain text without restriction.


56 | XMetaL | Working with files

By default, if you are editing in well-formed mode, the Attribute Inspector and Element List display only elements and 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 it becomes well-formed. However, since there is no DTD to indicate the structure of the elements, the results may not be what you want. • SGML documents cannot be edited without a DTD or rules file.

Create a well-formed XML document 1. 2. 3. 4. 5. 6.

Click File ➤ New. Click the Well-formed tab. Click the Blank Well-Formed XML Document icon. Click Open. Add elements to your new document. Add elements to your new document (see below). (You cannot enter content until you have created at least 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/or other elements. Element is empty. Enable this option if you do not want the element to have any content.

Define an attribute All 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.


XMetaL | Working with files | 57

Printing documents Printing is available from all three document editing views: Normal, Tags On, and Plain Text. The document prints as it appears in the current view, with tags icons in Tags On view, and as source code in Plain Text view. 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 â&#x17E;¤ Print. 2. Optional: Click Options and create headers and footers.

Print from a browser 1. Click View â&#x17E;¤ Page Preview. 2. Right-click in the browser pane and choose Print.


58 | XMetaL | Selecting and editing text

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 document that contains markup as well as text. This topic describes how to use XMetaL Author to work with the text in your 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 creating an invalid document by deleting or moving markup inappropriately. For example, each time you select a start or 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.


XMetaL | Selecting and editing text | 59

Selection of an element start tag (Emphasis) but not the end tag:

To select this:

Do this:

A single word

Double-click the word you want to select.

A single element

Click Edit ➤ Select Element.

Consecutive elements

Click anywhere in the first element to be selected and drag in the appropriate direction until all of the elements are selected.

The entire contents of a document

With the insertion point anywhere in the document, press Ctrl+A.

Editing selections In XMetaL Author, you can cut, copy, and paste selected text and markup using menu commands, shortcut keys, or by dragging and dropping. However, just as there are rules for selecting text and markup, there are also rules about how and where text and markup can be deleted or inserted. Removing or pasting certain elements can cause invalid markup in some circumstances. Usually, you cannot delete a selection if it includes required elements. Similarly, XMetaL Author will not paste a selection that would cause the markup to become invalid.

Copy and paste a selection 1. Select the part of the document that you want to copy. 2. Do one of the following: • •

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. 2. Do one of the following: • •

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


60 | XMetaL | Selecting and editing text

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 â&#x17E;¤ Delete. Note: If rules checking is on, XMetaL Author does not delete selections that contain required elements.


XMetaL | Finding and replacing text | 61

Finding and replacing text In XMetaL Author, you can find and replace text, elements, and entities. Find and replace operations are similar 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 are searching 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 rules checking 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, matching upper-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 are interpreted as patterns). If this option is disabled, any special search characters in the search or replace text are treated as ordinary characters. • Search backwards. Enable this option to search for the requested word from the current location towards the beginning of the document. • Wrap. Enable this option to search from the current location to the bottom of the the document, and then continue 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 this option is disabled, an error message appears whenever XMetaL Author attempts to replace text within a read-only element.

Searching for text You can search for text that occurs anywhere in your document, and replace it with different text or with a text entity. You can also restrict your search so that you find specific text only when it occurs within a specific element.

Find and replace text 1. 2. 3. 4. 5. 6.

Click Edit ➤ Find and Replace. In the Find box, type the text that you want to find. In the Replace with box, type the replacement text (if any). Click Options and set search options as required. Click Find. 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


62 | XMetaL | Finding and replacing text

Find and replace text within a specified element Click Edit ➤ Find and Replace. In the Find box, type the text that you want to find. In the Replace with box, type the replacement text (if any). Click Options. In the Within Element list box, choose the element to which you want to restrict the search. Set additional search options as required. 6. Click Find. 7. When XMetaL Author finds an occurrence of the text, do one of the following: 1. 2. 3. 4. 5.

• •

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 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 entity reference that you want to use to replace text. Remember to include the opening ampersand (&) and closing semi-colon (;), for example &ProductName;. 4. 5. 6. 7.

Click Options. Enable the Replace with entity option. Set additional search options as required. Click Find. When XMetaL Author finds an occurrence of the text, do one of the following: • •

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 so does not invalidate the markup. The element content does not change. You can also limit the search to elements that occur within a specific parent element. For example, you might want to search for Para elements that occur inside an LI element. You can select an element in the Element tab of the Find and Replace dialog. All elements defined in your DTD or Schema are listed here.


XMetaL | Finding and replacing text | 63

Searching for attribute values You can search for elements with specific attribute values by following the element name with a space-separated list consisting of attribute names followed by an equals sign (=) and a value in double quotes (" "). For example: <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 following 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 replacement text 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 a null 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 expects an exact character for character match when peforming a find and replace. Also, attribute order in the XML source is important.

Find and replace elements 1. 2. 3. 4. 5. 6. 7.

Click Edit ➤ Find and Replace. Click the Element tab. In the Find list box, choose the element that you want to find. In the Replace with box, type or select the replacement element (if any). Click Options and set additional search options as required. Click Find. 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 can also restrict your search so that you find the entity reference only when it occurs within a specific element.


64 | XMetaL | Finding and replacing text

Find and replace an entity reference 1. Click Edit ➤ Find and Replace. 2. Click the Entity tab. 3. In the Find box, type the entity reference that you want to find. Remember to include the opening ampersand (&) and closing semi-colon (;), for example &ProductName;. Note: The search is case-sensitive. 4. 5. 6. 7.

In the Replace with box, type the replacement entity reference (if any). Click Options and set search options as required. Click Find. 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 1. Click Edit ➤ Find and Replace. 2. Click the Entity tab. 3. In the Find box, type the entity reference that you want to find in the current document. Remember to include the opening ampersand (&) and closing semi-colon (;), for example &ProductName;. 4. 5. 6. 7. 8.

In the Replace with box, type the replacement text (if any). Click Options to expand the dialog box. Enable the Replace with text option and set additional search options as required. Click Find. 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. That is, 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.) The following special characters can be used: . * ? + ^ $ [ ]

In addition, the character < is used to indicate an element search when it appears as the first character in the pattern.


XMetaL | Finding and replacing text | 65

To search for any special character as ordinary text when Use Pattern Matching is turned on, precede it with a 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 specific regular expression syntax.

Search pattern summary Expression

Matches

Example

ordinary character

itself

“abc” matches “abc”

<name or <name>

the element name

&name or &name;

the entity name

.

any single character

“fo.d” matches “food”

x*

0 or more occurrences of the char-

“l*ama” matches “llama”

acter x (pattern)*

0 or more occurrences of the pattern “b(an)*a” matches “banana”

x+

1 or more occurrences of the char-

“be+n” matches “been”

acter x (pattern)+

1 or more occurrences of the pattern “b(an)*a” matches “banana”

x?

0 or 1 occurrences of the character “colou?r” matches “color” and “colour” x

(pattern)?

0 or 1 occurrences of the pattern

“b(an)*ale” matches “banale” or “bale”

pattern1 | pattern2

pattern1 or pattern2

“(love|money)” matches “love” or “money”

^pattern

pattern immediately following

“^Note” matches “Note” at the start of a paragraph (as

markup

in <p>Note...</p>)

pattern$

pattern immediately before markup “sub$” matches “sub” at the end of a paragraph (as in <p>...sub</p>)

[string]

any single character in the string

“t[ai]n” matches “tan” and “tin”

[^string]

any single character not in the string “th[^e]n” matches “than” , but not “then”

[char1-char2]

any character in the range

“[a-c]” matches “a”, “b”, or “c”

[^char1-char2]

any character not in the range

“[^a-c]” matches none of the characters “a”, “b”, or “c”


66 | XMetaL | Finding and replacing text

Expression

Matches

\n

in a replace string, it is replaced by If the search text is “(.)read” and the replace text is the text matched by the nth sub-

Example

“\1ox”, the result is “box”

expression in brackets in the search string \0

in a replace string, it is replaced by If the search text is “fish” and the replace text is “gone the text matched by the entire search \0ing”, the result is “gone fishing” string


XMetaL | Working with lists | 67

Working with lists If XMetaL Author has been customized to recognize list elements in your DTD or rules file, or if you are using DITA, 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 item to a nested list, convert a group of paragraphs to a list and vice-versa, and convert a list from one type to another.

Insert a list 1. In the document, click where you want to insert a list. 2. Do one of the following: •

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, you can press Enter in a list item to insert a new list item after the current one. If the contents are surrounded by 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 press Enter only once. If the list item contents are surrounded by a sub-element, press Enter three times.

Insert a list item You 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. 2. Do one of the following: • •

Click Insert ➤ List Item and select a list type Press Enter

Insert a list within a list This 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).


68 | XMetaL | Working with lists

2. Press Tab. You can edit this list as you would any other list. To terminate this list and create a new sub-list, press Enter twice. To return to the original list, press Enter again (the new sub-list is deleted, unless it has some content).

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. 2. Do one of the following: â&#x20AC;˘

If you are working in a DITA document, click Insert â&#x17E;¤ List and select a list type

â&#x20AC;˘

Click

or

on the Formatting toolbar

Convert list items to paragraphs This 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 lists Definition lists are a special kind of list because instead of consisting of ordinary list items, they consist of a combination of terms and definitions. A basic definition list consists of alternating terms and definitions, but you can also have several terms or definitions in sequence. Of course, you do not have to use this kind of list just for definitions: you can use it for 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, or if you are using DITA, you can take advantage of various editing features.


XMetaL | Working with lists | 69

To insert a definition list, use the Element command in the Insert menu. The following editing shortcuts are available: • 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.


70 | XMetaL | Working with images

Working with images You can insert images into an XML or SGML document if XMetaL Author has been configured to recognize one or more elements in the DTD as image elements. If you are working in DITA, you can insert an image or 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 often inserted 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 in browsers that cannot display the image itself. • Vertical alignment. This property refers to the alignment of an inline image relative to the text on either side of it. For example, if the vertical alignment is set to the bottom, the bottom of the inline image lines up with the bottom of the text on either of side of it; if the vertical alignment is set to the top, the top of the image 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 element in XML and SGML documents. The DTD should declare for HTML:IMG at least the common attributes of the HTML IMG element: SRC, ALT, HEIGHT, and WIDTH.

Insert an image You 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 enter both a width and a height. 4. Click OK. When you insert an image in a DITA document, XMetaL inserts an <image> element. Alternative text (if any is specified) is saved in the <alt> element. The <alt> element is a child of the <image> element.


XMetaL | Working with images | 71

Insert a figure with a title You can insert a figure with a title into a DITA document through the Insert menu. The figure includes an image 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 enter both a width and a height. XMetaL inserts a <fig> element that contains child <title> and <image> elements. Alternative text (if any 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 the DOCTYPE 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 choosing an entity from the dropdown list. XMetaL Author automatically sets the height and width attributes (if specified by the customization).

Edit image properties You can edit image properties through the Attribute Inspector. If you are using DITA, you can use the Image or Figure Properties dialog. 1. Select an image. 2. Do one of the following: • •

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 contents of the <alt> element. If the <alt> element does not exist, the contents of the alt attribute are displayed.

Displaying images Images appear in the XMetaL Author and XMetaL XMAX document pane similar to how they appear in a browser, including image size and, if applicable, transparency.


72 | XMetaL | Working with images

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 Name

File extension

Notes

Windows Bitmap

BMP

Only the Windows BMP format is supported.

Encapsulated PostScript

EPS

EPS files must contain an embedded TIFF header.

Graphic Interchange Format GIF (Compuserve) Joint Photographic Experts Group

JPG (or JPEG, JPE, JFIF, JIF)

Windows Icon

ICO

Windows Metafile

WMF

Enhanced Metafile

EMF

Portable Network Graphics

PNG

Tagged Image File Format

TIF (or TIFF)

PC Paintbrush

PCX

Only the first image in an animated GIF is displayed.

WMF files must include a placeable header.

Only the first image in a file containing multiple images is displayed.

Truevision Graphics Adapter TGA or TARGA Scalable Vector Graphics

SVG

Requires installation of an SVG viewer (for example, Adobe SVG Viewer).


XMetaL | Working with tables | 73

Working with tables XMetaL Author supports the CALS table model and the HTML table model. DITA supports the CALS table model only. If you are working in a DITA document, you can insert a CALS table, a simplified version of the CALS 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 can use the commands in the Table menu to insert and edit a table in Normal and Tags On view. XMetaL Author does 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. Table editing 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 other applications 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 View menu. 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, after backspacing and removing a cell) by clicking Table ➤ Repair Table Structure.

HTML tables If your DTD or schema declares the <TR> and <TD> elements as part of its table model, XMetaL Author assumes 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 just individual rows, columns, or cells) from the Insert Table dialog box when you insert a table. You can also use the Table Properties dialog box at any time to change table formatting, or to set the properties of individual columns, 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.


74 | XMetaL | Working with tables

HTML table properties You can set table, column, row, and cell properties through the Table Properties dialog. You can set other table properties through the Attribute Inspector. Note: Depending on how the HTML table model is set up in your document DTD or schema, some properties may not be available. Note: Changing some of the table properties may not yield visible changes to the tables, although the underlying XML content does change. Tab

Property

Table

Background color Table width Border Border width Cell spacing Cell padding

Column

Background color Column width Vertical alignment Horizontal alignment Cell type

Row

Background color Row height Vertical alignment Horizontal alignment Cell type

Cell

Background color Row height Cell width Vertical alignment Horizontal alignment Cell type

Insert a table caption 1. Click anywhere inside the table. 2. Click Table â&#x17E;¤ 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 ALIGN attribute, the caption continues to appear above the table in XMetaL Author, but appears centered below the table in most browsers.


XMetaL | Working with tables | 75

Edit a table caption 1. Click anywhere inside the table. 2. Click Table â&#x17E;¤ 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 ALIGN attribute, the caption continues to appear above the table in XMetaL Author, but appears centered below the table in most browsers.

CALS tables If your DTD or schema declares the <TGROUP> element as part of its table model, or if you are working in a DITA document, XMetaL Author assumes the CALS model. The CALS Table Model DTD is defined by the OASIS organization. CALS tables can consist of three parts: a table header, the table body, and a table footer. You can insert a header and footer when you insert the table, or you can edit an existing table to set rows as header and footer rows. Although headers and footers are optional, their position is not. Headers are always the top row(s) of the table, and footers are always the bottom row(s) of the table. If you want to add a header or footer after inserting 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 150 rows or columns, no error message appears, but the new table contains only 150 rows or columns. If you need a table with more than 150 rows or columns, you can add the required rows or columns to the table after you create it. You can nest CALS tables by putting the insertion point inside a table cell and inserting a new table. The CALS model as defined by OASIS calls for tables to be nested to one level only; however, depending on the structure of your DTD, you may be able to nest more than one level in your CALS table. Nested CALS tables consist 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, and cells from the Table Properties dialog box.

CALS table properties XMetaL 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 the underlying XML content does change. Table element

Property

Table

Frame Column separator Row separator Horizontal alignment

Column

Name Column width


76 | XMetaL | Working with tables

Table element

Property Column separator Row separator Horizontal alignment

Row

Row separator Vertical alignment Row type

Cell

Column separator Row separator Horizontal alignment 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 expressed as a number followed by an asterisk (*), for example, 2*. The numbers associated with each proportional width are combined to form a ratio that describes how portions of the total table width are distributed among all the columns that have proportional widths (after all columns that have specific widths get their share). The default column width is 1*. For example, suppose your table has four columns and a width of four inches, and the column widths are specified as 1*, 2*, 3*, and 1in. The widths of the four columns are calculated as follows: the fourth column has a width of one inch, because its width is specified explicitly. This leaves three inches to be distributed among the other three columns according to the ratio 1:2:3 (that is, the second column is twice as wide as the first column, and the third column is three times as wide as the first). This means that the first column is 0.5 inches wide, the second column is 1.0 inches wide, and the third column is 1.5 inches wide.

Insert a table You 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 â&#x17E;¤ 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 of table, 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 1. Click anywhere inside the table. 2. Click Table â&#x17E;¤ Table Properties.


XMetaL | Working with tables | 77

3. Click the Table tab. 4. Set table properties as required.

Format a column 1. Click anywhere in the column you want to modify. 2. Click Table ➤ Table Properties. 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 within the current table. 5. Set column properties as required.

Format a row 1. Click in the row you want to modify. 2. Click Table ➤ Table Properties. 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. 2. Click Table ➤ Table Properties. 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 row or column, or a block spanning two or more rows and columns. 2. Click Table ➤ Table Properties. 3. Click the Selection tab. 4. Set selection properties as required.


78 | XMetaL | Working with tables

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 is inserted 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, the cursor 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 columns for purposes of navigation. If a cell spans two or more rows, the cell is considered to be in the topmost of those 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.


XMetaL | Working with tables | 79

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 1. Do one of the following: • •

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 the row 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 table by holding down the Shift key while you drag the right edge of the column to the desired width.

Change the height of a row You can specify the height of a row in an HTML table. 1. Click anywhere inside the row that you want to resize. 2. Click Table ➤ Table Properties. 3. Click the Row tab. 4. Type the height, in pixels, in the Row height box.


80 | XMetaL | Working with tables

Change the width of a column 1. Click anywhere inside the column you want to resize. 2. Click Table ➤ Table Properties. 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 that spans more than one row or column. Splitting a cell means dividing one cell into two, either vertically (splitting into columns) or horizontally (splitting into 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 a cell 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 is not 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.


XMetaL | Working with tables | 81

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 empty cell 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 content to 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 cell content 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 adjacent cells 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 target cell 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 adjacent cells 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 cell content. 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 target cell block is overwritten with the copied content.


82 | XMetaL | Working with tables

Note: You can also copy your selection by holding down the Ctrl key while you drag and drop the selected 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 spreadsheets and text editors, into XMetaL Author. This material is inserted as an HTML or CALS table, according to the format 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 have content. 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 is no problem with pasting them. Material from text editors such as Notepad can also be pasted, and is automatically converted into a table as long as it conforms to the above guidelines.


XMetaL | Marking changes to text | 83

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 authors and reviewers to be able to quickly spot the changes made since they last viewed the document. Also, they may 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 or deletions. When change tracking is active, text that is inserted in a document appears in a different color than the 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 has been deleted. The default settings show insertions as red underlined text, and deletions as blue text with strikethrough marking applied, but you can change the color for both insertions and deletions, or you can set XMetaL Author to use different colors for different contributors’ additions and deletions. You can also change the additional text formatting for insertions. When you rest the mouse pointer over text that has been marked as changed, a popup, or tooltip, displays the name of the user who made the change, the nature of the change (insertion or deletion), and the date the 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 change tracking was on.


84 | XMetaL | Marking changes to text

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 reject each change individually. When marked changes are accepted, the changes are incorporated into the document, and the revision marks are removed from the relevant text. When marked changes are rejected, the changes 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. 3. Do one of the following: • •

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 necessary to make the document valid.


XMetaL | Using the writing tools | 85

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 rest of the proofreading session. • Replace words by choosing a word from a list of available words, by typing in the correct word, or by defining an 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 a document. For example, you can choose how the spell checker starts and whether it searches for misspelled words, irregular capitalization, duplicate words, and words with numbers. Note: The spell checker does not check the spelling of processing instructions, comments, hidden elements, entity references, or form fields.

Check spelling You can check the spelling of an entire document or a selection. Click Tools ➤ Spell Checker. Make a selection from the Check list box. Click Start. When checking stops at a misspelled word, choose a word from the Replacements box or type the replacement in the Replace with box. 5. Do one of the following: 1. 2. 3. 4.

• •

Click Replace to replace the current word Click Auto Replace to replace all occurrences of the word in the document

Ignore a flagged word 1. 2. 3. 4.

Click Tools ➤ Spell Checker. Make a selection from the Check list box. Click Start. When checking stops at a word you do not want to change, do one of the following: •

Click Skip once


86 | XMetaL | Using the writing tools

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 lists of acceptable words. There are two types of word lists: main word lists, and user word lists. When the spell checker is checking a word 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 determined 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 spell checker to use both English and French main word lists, you can add whichever of these main word lists is not the default. Any word lists that you add in this way can also be removed.

Add a main word list 1. Click Tools ➤ Spell Checker. 2. 3. 4. 5.

Click Options ➤ Main Word Lists. Click Add List. Select the main word list you want to add. Click Open.

Remove a main word list 1. Click Tools ➤ Spell Checker. 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 to a user word list, and specify whether you want the spell checker to skip them, replace them with a different word automatically, or suggest alternatives for them. For example, you can specify replacements for words that you frequently misspell or mistype, or you can add words that you do not want the spell checker to flag.


XMetaL | Using the writing tools | 87

User word list files have the extension .uwl. The word list that is installed by default is WT10xx.uwl (where xx is the two-letter code for the language or language variant you are using for spell checking). This file is available to any document created or edited in your setup of XMetaL Author. If you have more than one of these lists installed on your system, you can add or remove them from the set of word lists that the spell checker uses for your document. In addition to the default word list, each document has its own word list. Any time you ignore a word during spell checking by clicking Skip All, that word is added to the document user word list.

Set the default user word list 1. Click Tools ➤ Spell Checker. 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 1. Click Tools ➤ Spell Checker. 2. 3. 4. 5.

Click Options ➤ User Word Lists. Click Add List. Select the user word list you want to add. Click Open.

Add an entry to a user word list 1. Click Tools ➤ Spell Checker. 2. Click Options ➤ User Word Lists. 3. Click the word list to which you want to add an entry. 4. Do one of the following: • •

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 1. Click Tools ➤ Spell Checker. 2. 3. 4. 5.

Click Options ➤ User Word Lists. Choose a word list. Click the entry you want to delete. Click Delete Entry.


88 | XMetaL | Using the writing tools

Change the replacement text for an entry in a user word list 1. Click Tools ➤ Spell Checker. 2. 3. 4. 5. 6.

Click Options ➤ User Word Lists. Click a word list. Click the entry you want to change. Edit the text in the Replace With box. Click Replace Entry.

Change an entry in a user word list 1. Click Tools ➤ Spell Checker. 2. 3. 4. 5. 6.

Click Options ➤ User Word Lists. Click the word list that contains the entry you want the spell checker to handle differently. Cick the entry you want to change. Click Properties. 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 a document.

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 choice must 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 available for 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 information for 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.


XMetaL | Using the writing tools | 89

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. A second 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. 2. 3. 4. 5. 6.

Click Tools ➤ Thesaurus. Click Look up. Expand the desired definition to display a list of synonyms and other related words. Click the word you want to use to replace the original word in the document. Click Replace. Note: The thesaurus may prompt you to select the correct form of the word you want to insert. This happens 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”, which can be used as either a noun or a verb).

Insert a word from the thesaurus 1. 2. 3. 4. 5. 6. 7.

Click Tools ➤ Thesaurus. Type the word you want to look up in the list box at the top of the Thesaurus page. Click Look up. Expand the desired definition to display a list of synonyms and other related words. In your document, click where you want to insert the word. Click the word you want to insert. Click Insert. Note: The thesaurus may prompt you to select the correct form of the word you want to insert. This happens 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”, which can be used as either a noun or a verb).

Set thesaurus options 1. Click Tools ➤ Thesaurus. 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 contains the 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 word from the thesaurus into your document. • Spelling assist. Enable this option to have the thesaurus suggest alternate spellings if the word you want to look up is spelled incorrectly or not found in the thesaurus. Options with check marks beside them are currently enabled.


90 | XMetaL | Using the writing tools

Any options you change remain in effect the next time you open the Thesaurus.

Set thesaurus look-up options 1. Click Tools ➤ Thesaurus. 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 word being 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 is a 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 one type 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 up is 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 being looked 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 when they 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 thesaurus entries include only some of the look-up options.

Set the thesaurus data file 1. Click Tools ➤ Thesaurus. 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 XMetaL Author was installed. If the data file you want to select is not available, you must reinstall XMetaL Author and specify different language options as part of the installation wizard. See install_readme.html on the XMetaL Author CD for more information.


XMetaL | Using the writing tools | 91

Specifying the language settings XMetaL Author supports four variants of English (British, American, Canadian, and Australian), two variants of French (French national and Canadian), and two variants of German (German national and Swiss). You can choose a language for the current file or set it as the default language for all of the writing tools. You can also 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 check for the formatting conventions of another language. For example, the spelling checker can format all dates in a document according to specific conventions (such as “12 avril 1996” for French).

Set the language 1. Click Tools ➤ Spell Checker. 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 supported by the current writing tool.

Add a language 1. Click Tools ➤ Spell Checker. 2. Click Options ➤ 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 1. Click Tools ➤ Spell Checker. 2. Click Options ➤ 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 were included when XMetaL Author was installed cannot be removed using this method. If you want to remove an installed language, you must reinstall XMetaL Author and specify different language options as part of the installation wizard. See install_readme.html on the XMetaL Author CD for more information.


92 | XMetaL | Using the writing tools

Setting spell checker options You can specify the following spell checker options through the Spell Checker menu in the Tools menu. Your settings are applied the next time you open the spell checker. Option

Description

Auto start

Starts spell checking automatically from the beginning of the document when you open the spell checker.

Beep on misspelled

Sounds an alert when the spell checker finds a word it does not recognize.

Recheck all text

Re-checks all spelling from the beginning of the document when you interrupt the spell checker and then press Resume.

Check words with numbers

Checks for words that contain numbers (for example, postal codes).

Check duplicate words

Checks for duplicate words.

Check irregular capitalization

Checks for incorrect capitalization (for example, two uppercase letters at the beginning of a sentence).

Prompt before auto replacement

Asks for user input before replacing a word.

Show phonetic suggestions

Suggests words that sound similar to a flagged word.

Setting thesaurus options You can specify the following thesaurus options through the Thesaurus menu in the Tools menu.Your settings are applied the next time you open the thesaurus. Note: Most thesaurus entries include only some of the options listed below. Table 2: General options Option

Description

Auto look-up

Displays the thesaurus entry for the current word when the thesaurus is opened.

Auto close

Closes the Writing Tools dialog box after you insert a word from the thesaurus into your document.

Spelling assist

Suggests alternate spellings if the word is spelled incorrectly or not found in the thesaurus.


XMetaL | Using the writing tools | 93

Table 3: Look-up options Option

Description

Synonyms

Displays words that have the same or similar meaning as the word being looked up.

Antonyms

Displays words that have an opposite meaning.

Related words

Displays words that have a similar meaning, but are not as close as synonyms.

Is a type of

Displays words for items or ideas that include the word being looked up. For example, if the selected word is tree, this list might contain “plant”.

Has types

Displays words that have meanings that are a subset of the word being looked up. For example, if the selected word is “tree”, this list might contain “evergreen”.

Is a part of

Displays words for items or ideas for which the word being looked up is a component. For example, if the selected word is “tree”, this list might contain “forest”.

Has parts

Displays words for items or ideas that are a component of the word being looked up. For example, if the selected word is “tree”, this list might contain “branch”.

Example

Displays a sample phrase that illustrates the correct use of the word.


94 | XMetaL | Using macros

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 does not have a built-in shortcut key or command. Macros may also perform some special functionality outside of the normal XMetaL Author functions. Such macros are created for you by your customizer, and are available from the Macros dialog box. Depending on the customization, you may also be able to run them through toolbar buttons or menu commands. See your customizer for details. Macros are stored in macro files, which have the extension .mcr. You may have macros from as many as four 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 the macro is run. Therefore, there are some actions that cannot successfully be included in a macro. As a general guideline, if a macro involves any of the commands that open dialog boxes, that action should be completed somewhere in the macro. (Commands or buttons that open dialog boxes usually have an ellipsis (...) after the command or button name.) For example, you can create a macro that inserts a particular element, but you 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 the mouse to change the selection, you will hear an alert. The second time, a message appears saying that you should 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 can usually be played back in the other view. Macros recorded in the Plain Text view are less likely to work in the other 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


XMetaL | Using macros | 95

• 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 macro files: • Global macro file for all users. Macros/xmetal.mcr contains macros available to all users for all documents. 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 macros available 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 related DTD), 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 (where dtdname is the name of the related DTD), contains macros available to the current user for any document based 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 folders on a regular basis. For this reason, it is often safer to store your recorded macros in one of the two macro files 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. 4. 5. 6. 7.

Click Tools ➤ Stop Recording. Select an option from the Create this macro for list. Type a name for your macro in the Macro name box. Optional: Specify a shortcut key combination to associate with the macro. Optional: Specify an image to associate with the macro. This image appears beside the macro name in the Macros dialog box.


96 | XMetaL | Using macros

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 (a keyboard shortcut), or you can create a toolbar button or menu command for the macro. You can set the keyboard shortcut at the time you record the macro. You can also change a keyboard shortcut for any macro at any time.

Set the keyboard shortcut for a macro 1. 2. 3. 4.

Click Tools ➤ Macros. Select a macro. Choose a shortcut key combination. 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 the current 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 Click View ➤ Toolbars. Click the Menu tab. Click the name of the menu or submenu to which you want to add your new command. Click Add Menu Item. From the Macros list in the Properties area, select the macro that you want to associate with the menu command. 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: 1. 2. 3. 4. 5.

• •

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


XMetaL | Using macros | 97

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, and from the corresponding macro file. It does not reload the next time you start XMetaL Author (unless XMetaL Author is customized to overwrite macro files with fresh copies from a central server every time it starts).

Delete a macro 1. Click Tools â&#x17E;¤ Macros. 2. Select a macro. 3. Click Delete.


98 | XMetaL | Using the Resource Manager

Using the Resource Manager The Resource Manager is an asset management tool that gives you access to many kinds of objects, or assets.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 additional tabs 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 using the intelligent insertion operations. The Desktop tab provides an Explorer-like view of your desktop from which you can drag and drop files into your 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 contents of 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 the toolbar 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. In order 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 choose objects from your system to insert into your documents, or to save as part of your assets collection in the Assets tab. You can use the Resource Manager toolbar, in the Contents pane of the Desktop tab, to navigate through folders, 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 of menus 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.


XMetaL | Using the Resource Manager | 99

Inserting objects in your document You can insert objects that have been stored as assets into your document from the Asset tab of the Resource Manager. You can also use the Desktop tab to drag into your document objects that have not been stored as assets. In general, however, to take advantage of the intellingent insert capabilities, it is best to add objects to 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 into your document, and do one of the following: â&#x20AC;˘ â&#x20AC;˘

If the object (for example, an image) is to be inserted at a specific location in the document, drop it at the 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 drop it 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 Manager collection in order to take advantage of its intelligent insertion capabilities. You should store these files in the My Assets folder. You can create your own folders within the My Assets folder to organize and categorize objects to insert into your documents. The categories of assets that you can create are defined by asset templates, which are a set of folders located in the Asset Templates folder. A set of customizable templates is located in the Customizable Asset Templates folder underneath the Assets folder. If you want to make these templates available, use the Desktop tab or Windows Explorer to copy the contents of the Customizable Asset Templates folder to the Asset Templates folder. Most of these templates are ready for use; others (Images {Specific Tag}) need to be further customized for your particular DTD. Note: You do not have access to the Asset Templates folder from the Assets tab of the Resource Manager. To see the contents of the Asset Templates folder, you must use either the Desktop tab or Windows 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.


100 | XMetaL | Using the Resource Manager

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 or docbook-code. 4. Choose an asset type from the Type of Assets list box to specify the types of objects (assets) you plan to put in that folder. The asset types listed in the Type of Assets list box are determined by the template folders available in the 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 this folder using Windows Explorer, and click the new folder in the Explorer pane of the Assets tab, the Contents pane displays a Convert to Assets page. Click Convert on this page to perform the conversion. A dialog box 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 into appropriate asset folders. 3. Do one of the following: â&#x20AC;˘ â&#x20AC;˘

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 select the 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.


XMetaL | Importing databases | 101

Importing databases If your customization allows it, you can import the contents of a database or spreadsheet file into your document as a table. The database import feature generates an SQL query that you can view and then modify to import only 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 Import Database 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 by clicking the View SQL tab on the Import Database dialog box.You can view a plain text version of the imported data by clicking the Data Preview tab.

Import a database 1. 2. 3. 4. 5. 6.

Choose the database to import. Choose the fields to be inserted into the table and set the order of the fields. Set the appearance of the fields and filter the records to be imported. Set the appearance of the fields and filter the records to be imported. Optional: Preview your query by clicking the Data Preview tab on the Import Database dialog box. 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 a single file. All other supported database types create source databases in a folder, which may contain several files, 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 applications to use the database). A DSN is a database file that has already been assigned a descriptive name and associated with a database driver. 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.


102 | XMetaL | Importing databases

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. 3. Do one of the following: â&#x20AC;˘ â&#x20AC;˘

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. 2. 3. 4.

In the Database area of the Import Database dialog box, click Select. Enable the DSN option. Select the DSN that you want to import into your document. 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 Available Fields list on the Query Builder page of the Import Database dialog box.You now need to create your database query 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 1. In the Import Database dialog box, click the Query Builder tab. 2. In the Available Fields list, select a field. Note: To remove more than one field, hold down the Ctrl or Shift key.


XMetaL | Importing databases | 103

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 only certain records according to the content of one or more fields.

Edit field properties 1. 2. 3. 4.

In the Import Database dialog box, click the Query Builder tab. In the Selected Fields list, select a field and then click Edit. In the Display Name text box, type the name for the field as you want it to appear in your table. 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 in the 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 the value(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 using the 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 following structure: â&#x20AC;˘ The table is surrounded by the <DATA> element. â&#x20AC;˘ Each table row is represented by a <RECORD> element.


104 | XMetaL | Importing databases

â&#x20AC;˘ <RECORD> elements contain tags that correspond to the display name (as set in the Query Builder tab) for each 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 area of 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 and attributes are declared in your DTD. In the Output Names area of the Output Format page, you can specify the casing that is correct for your DTD. In the table of names, the Element/Attribute column displays the generic element and attribute names. The Name 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 Horizontal if 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 is necessary 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 least one field in common. For example, two tables of employee information (a payroll table and an employee information table) could both have an employee ID field. (The field names do not have to be identical, but the type of data must be the same.)


XMetaL | Importing databases | 105

You can then create a new output record that joins records in the two tables by matching up values in the shared field. For example, you could create records consisting of a salary value from the payroll table and a name from the employee information table.The salary is paired with the correct name because their employee ID values match. Note: A field does not have to be in the Selected Fields list in order to be used in a join. An unselected field can be the field that is matched to the corresponding field in the second table, but that does not appear in the final table. When you join tables, the fields of the joined table appear in the Available Fields list in the Query Builder section. You can add add and edit the fields just as you would for a non-joined table.

Ceate a joined table query XMetaL Author uses SQL. 1. In the Import Database dialog box, click the Query Builder tab. 2. From the Table list box, select a table from the current database. This is the primary table (the table to which 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 1. 2. 3. 4.

In the Import Database dialog box, click the Query Builder tab. Click Table Joins. Select a join. Click Remove.

Update a table The 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.


106 | XMetaL | Customizing XMetaL Author

Customizing XMetaL Author When you first launch XMetaL Author out of the box, there is no default template, only the Standard and Formatting toolbars are visible, and no document is loaded. In this capacity, XMetaL Author functions as a general-purpose XML and SGML editor. However, you may find that you need to customize XMetaL Author for 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 can specify whether you want it to apply to all documents, or only to documents based on the current DTD. You can also specify whether you want the macro to be available to all XMetaL Author users who work from the same 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’s Guide.

Customizing environments for multiple users When you work with XMetaL Author on a shared computer, your user options, macros, and toolbar and menu configuration 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. The next time you log on and start XMetaL Author, your workspace and personal preferences are automatically loaded. In Windows XP and 2000, the personal settings folder is usually ..\Documents and Settings\<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, it searches the XMetaL Author installation folder (usually ..\Program Files\XMetaL 5\Author\) and loads the file from there. • dtdname.tbr (toolbar and menu settings). When you exit XMetaL Author or close all documents based on the DTD, dtdname.tbr is saved to both the Rules folder (unless the associated .tbr file in that folder is readonly) and to your personal settings folder, even if you have not made any changes to the toolbar and menu configuration. • dtdname.mcr (macros specific to a DTD). If a macro in the dtdname.mcr file in the XMetaL Author folder has 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 has the 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 Author interface (for example, in the Options or Find and Replace dialog boxes) are saved in this file. XMetaL


XMetaL | Customizing XMetaL Author | 107

Author makes changes only to the xmetal50.ini file in your personal settings folder, never to the general xmetal50.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 creates them in the same folder as the related DTD or rules file. If you want to save customization and cascading style sheet files in the personal settings folder, you must move or copy them to the folder. Once XMetaL Author finds these files in your personal settings folder, any style or customization changes you make are saved there. When you uninstall or update XMetaL Author, your personal settings folder and any macro files and cascading style sheets it contains are not removed. Therefore, you do not have to re-create these files when you reinstall XMetaL Author. Note: xmetal50.ini and any .tbr files are deleted from your personal settings folder when XMetaL Author is uninstalled.

Creating templates When you create a file with the New command, you must specify a template. Templates provide document outlines, and are also a quick way to create a new document that uses a particular DTD, schema, or rules file. You should create at least one template for each DTD, schema, or rules file. You may be able to create both an XML and an SGML template for the same DTD, depending on the complexity of the DTD. If the DTD was designed for XML documents, you should be able to create an SGML template for it. However, if the DTD was 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), you must choose a DTD or Rules file.

Create a template 1. 2. 3. 4. 5. 6.

Click File ➤ New. Click the General tab. Select Blank XML Document or Blank SGML Document and click Open. Choose a DTD, schema, or rules file to associate with your template. Add the desired markup and content. 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 schema to 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.


108 | XMetaL | Customizing XMetaL Author

Creating custom toolbars and menus You can create new toolbars and menus in XMetaL Author, and customize existing ones. Buttons and menu commands can be assigned to built-in commands or user-defined macros. You can create global or DTDspecific configurations: DTD-specific configurations are applied when you edit a document using the associated DTD. Global configurations apply to all documents. • To create global toolbar and menu configurations, carry out the customization steps when no document is open. • To create configurations for a specific DTD, perform the customizations when a document that uses that DTD 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 searches the folder specified by the tbr_path variable in the xmetal50.ini file. By default, this variable is set to the rules_path value. If it does not find the file in either of these places, it searches the folder that contains the DTD 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 not already have a .tbr file for the same DTD or schema in their personal settings folder, because their installation of XMetaL Author will load that .tbr file rather than the one that you have customized for them. If you delete the .tbr file from their personal settings folder, the next time they open a document based on the associated DTD, 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 a corresponding .tbr file in the Rules folder, then the .tbr file in the Rules folder is updated, and no .tbr file is created in the folder that contains the DTD or schema. • Some customized versions of XMetaL Author may not permit changes to the toolbars and menus. Check with your customizer for details.

Create a toolbar 1. 2. 3. 4.

Click View ➤ Toolbars. Optional: Click the check boxes to turn Show Tooltips or Flat Look on or off. Select the Toolbars tab and click New. Type a name and click OK. A small floating window appears near the top left of the XMetaL Author window. This is your custom toolbar.

5. 6. 7. 8.

Click the Buttons tab and select a category. Drag and drop buttons into the new toolbar. Optional: To create a separator line between buttons, click and drag the button to the right. Click Close.


XMetaL | Customizing XMetaL Author | 109

Associate a button with a macro You can create a new toolbar button, associate it with a macro and an icon image, and add it to a built-in or custom toolbar. Click View ➤ Toolbars. On the Toolbars tab, select the toolbar to which you want to add your button. Click the Button tab. From the Categories list, select Application Macros or dtdname Macros (where dtdname is the name of 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 on the toolbar. 1. 2. 3. 4.

Create a menu You can create new menus or sub-menus. 1. 2. 3. 4.

Click View ➤ Toolbars. Click the Menus tab. Click a menu in the tree structure on the left. Do one of the following: • •

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 (the underlined letter). For example, “M&ymenu”. The shortcut character you choose must be unique for that menu. 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 1. Click View ➤ Toolbars. 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 macro 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 menu command. 6. Specify properties as required. 7. Optional: click Move Up and Move Down to position the command.


110 | XMetaL | Customizing XMetaL Author

Setting options You can set the following options through the Tools menu. Settings are saved in the XMetaL configuration file in your personal settings folder. Table 4: General options Option

Description

Current user

Identifies documents by username and initials.

Location to temporarily store remote files

Specifies a location to temporarily store remote files.

Show tag tips

Displays attributes in a tooltip.

Show icons in menus

Displays icons in menus.

Restore last open documents

Re-opens documents that were open when XMetaL Author was last closed.

Table 5: View options Option

Description

Open new documents in

Specifies a default view for opening new documents.

Tag icons

Provides formatting information for tags in Tags On view.

Show inline images

Displays inline images.

Show comments

Displays comments in Tags On view.

Show structure view by default

Displays the structure view when opening a document.

Table 6: Plain text view options Option

Description

Font

Specifies a text font.

Syntax coloring

Specifies colors for markup and scripts.

Tab

Determines how tab characters are handled.

Word wrap

Specifies how to display lines that are longer than the width of the document pane.

Line numbering

Displays line numbers.

Table 7: File options Option

Description

New

Specifies a template for files created through the New Page button.


XMetaL | Customizing XMetaL Author | 111

Option

Description

Save as

Specifies a default extension when saving new documents.

Backups

Saves backup copies of your files.

File menu

Specifies the number of recently used documents to display in the File menu.

Automatic saves

Specifies the number of changes or minutes after which your document will be saved automatically.

End of line

Specifies line ending options for different operating systems.

Table 8: Change tracking Option

Description

Inserted text

Specifies format, color, and preview options for inserted text.

Deleted text

Specifies format, color, and preview options for deleted text.

Setting DITA options You 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 documents and select Tools ➤ DITA Options. To change DITA options on a specialization basis, open a specialized document and select Tools ➤ DITA Options. Show/hide domains With the exception of the Typographical domain, domains are groups of elements that are useful in specific industries 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 will be disabled or hidden in the user interface. The settings for show/hide domains are specific to the doctype or specialization. In the General tab, select a domain from the Hide these domains list and click the button to move it to the Show these domains list. Auto-assign element IDs You can control the automatic assignation of element IDs. By leaving the box checked, XMetaL automatically creates and assigns globally unique IDs to the elements. If this box is unchecked, the IDs must be manually assigned by content authors (by setting each element’s id attribute). The list of element types to auto-assign an ID is specific to the doctype or specialization. You can also indicate which elements have IDs automatically assigned to them by clicking Options and selecting elements.


112 | XMetaL | Customizing XMetaL Author

When you have set your DITA options to automatically assign element IDs, the following operations can result in 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 autoid 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 they do not occur in the same document instance. Problems with duplicate IDs were known to occur in earlier versions 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 prefix By 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 reference topics 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=""/>


XMetaL | Keyboard shortcuts | 113

Keyboard shortcuts Shortcut keys for XMetaL Author menu commands are indicated on their respective menus. All menus, menu items, and dialog box controls are accessible by pressing the Alt key and the underlined letter (also called an access key or mnemonic) associated with that control. XMetaL Author also supports shortcut keys for window and dialog box navigation. In addition to these mnemonic access keys for calling menu commands and dialog box controls, there are a variety 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 to see whether the keystroke combination has been assigned to a macro. If so, that shortcut activates the assigned macro rather than the default function outlined here.

File commands These shortcut keys give you access to file manipulation commands. Action

Shortcut

Create a new document from the default template

Ctrl+N

Create a new document by choosing a template

Ctrl+T

Open a document

Ctrl+O

Open a document from the recently-opened list

Alt+F + number key

Close a document

Ctrl+W OR Ctrl+F4

Save a document

Ctrl+S

Save all documents

Ctrl+Q

Print

Ctrl+P

Quit XMetaL Author

Alt+F4

Preview document in a browser

Ctrl+M

Display online help

F1

Editing commands These shortcut keys give you access to common editing operations. Action

Shortcut

Find and Replace

Ctrl+F

Find Next Forwards

F3

Find Next Backwards

Shift+F3

Find Selection Forwards

Ctrl+F3

Find Selection Backwards

Ctrl+Shift+F3


114 | XMetaL | Keyboard shortcuts

Action

Shortcut

Undo an action

Ctrl+Z OR Alt+Backspace

Redo an action

Ctrl+Y

Cancel an action

Esc

Check spelling

F7

Open thesaurus

Shift+F7

Validate Document

F9

Select all

Ctrl+A

Switching between views and display modes These shortcut keys switch between XMetaL Author's four editing views, and display invisible table grids. Action

Shortcut

Toggle between Normal and Tags On views

Ctrl + Space bar

Switch to Plain Text view

Ctrl+Shift+H

Switch to Tags On view

Ctrl+Shift+O

Switch to Normal view

Ctrl+Shift+W

Switch to Page Preview

Ctrl+Shift+V

Hide/show HTML table grid outlines (if no grid selected).

Ctrl+Shift+Q

Inserting, deleting, and moving text and markup These shortcut keys enable you to perform common editing operations on text and markup. Action

Shortcut

Delete one character to the left. If you are deleting from the Backspace first position in a tag, the first character in the tag to the left is deleted. Any empty tags in between the cursor and the text to be deleted are deleted as well. Delete one character to the right. If you are deleting from Delete the last position in a tag, the first character in the tag to the right is deleted. Any empty tags in between the cursor and the text to be deleted are deleted as well. Cut selection (copy to clipboard)

Ctrl+X OR Shift+Delete

Delete selection (do not copy to clipboard)

Delete

Copy selection

Ctrl+C OR Ctrl+Insert

Paste from clipboard

Ctrl+V OR Shift+Insert

Insert special character

Ctrl+Shift+E

Insert newline in PRE-like element

Enter

Terminate a PRE-like element

Shift+Enter


XMetaL | Keyboard shortcuts | 115

Action

Shortcut

Open or close the Attribute Inspector

Shift+F6

Open and place active cursor in the Attribute Inspector

F6

Split element (where allowed by the DTD)

Enter OR Ctrl+Shift+P

Join to preceding element (where allowed by the DTD)

Backspace (at beginning of element) OR Ctrl+Shift+J

Join to following element (where allowed by the DTD)

Delete (at end of element)

Remove markup

Ctrl+Shift+D

Open or switch Element List to “Change element” mode

Ctrl+Shift+L

Select element

Ctrl+Shift+T

Open or switch Element List to “Insert element” mode

Ctrl+Shift+I

Insert selected element from floating Element List dialog box, and dismiss dialog box

Ctrl+Shift+Enter

Insert a comment

F8

List formatting These shortcut keys perform list formatting. Action

Shortcut

Demote selected list items to sub-list

Tab

Promote selected list items out of list

Shift+Tab

Moving around in a document These shortcuts move the insertion point in the XMetaL Author document pane. See the next section for shortcuts for moving around in tables. Action

Shortcut

Scroll to insertion point or selection

F4

One character to the left

Left arrow

One character to the right

Right arrow

One word to the left

Ctrl + Left arrow

One word to the right

Ctrl + Right arrow

Up one line

Up arrow

Down one line

Down arrow

To the end of a line

End

To the beginning of a line

Home

Up one screen (scrolling)

Page Up

Down one screen (scrolling)

Page Down


116 | XMetaL | Keyboard shortcuts

Action

Shortcut

To the end of a document

Ctrl+End

To the beginning of a document

Ctrl+Home

Moving around in tables These shortcuts move the insertion point in tables. See the previous section for shortcuts for moving around in the rest of the document pane. Action

Shortcut

Next cell in a row

Tab OR Right arrow

Previous cell in a row

Shift+Tab OR Left arrow

First cell in a row

Alt+Home

Last cell in a row

Alt+End

First cell in a column

Alt+Page Up

Last cell in a column

Alt+Page Down

Previous row

Up arrow

Next row

Down arrow

Outside the table

Click to right of the table

Making and extending selections in a document These shortcut keys enable you to make or extend selections (highlighted text or markup). Action

Shortcut

One character to the right

Shift + Right arrow

One character to the left

Shift + Left arrow

To the end of a word

Ctrl+Shift + Right arrow

To the beginning of a word

Ctrl+Shift + Left arrow

To the end of a line

Shift+End

To the beginning of a line

Shift+Home

One line down

Shift + Down arrow

One line up

Shift + Up arrow

To the beginning of a document

Ctrl+Shift+Home

Select the current element

Ctrl+Shift+T

Select the entire document

Ctrl+A

Select the contents of the next cell in the table

Tab

Select the contents of the preceding cell in the table

Shift+Tab


XMetaL | Keyboard shortcuts | 117

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. Action

Shortcut

Extend selected cell block by one cell to the right

Shift + Right arrow

Extend selected cell block by one cell to the left

Shift + Left arrow

Extend selected cell block by one cell down

Shift + Down arrow

Extend selected cell block by one cell up

Shift + Up arrow

Choosing menu commands These shortcuts enable you to choose commands from the XMetaL Author menus. Action

Shortcut

Show the shortcut (right mouse) menu

Shift+F10

Show the program icon menu (on the program title bar)

Alt + Space bar

Select the next or previous command on the displayed menu Down arrow, Up arrow or sub-menu Select the menu to the left or right; or, with a sub-menu visible, switch between the main menu and the sub-menu

Left arrow, Right arrow

Close the visible menu and sub-menu at the same time

Alt

Close the visible menu; or, with a sub-menu visible, close the sub-menu only

Esc

Moving between panes, documents, and dialog boxes These shortcuts enable you to move between panes, dialog boxes, and documents. Action

Shortcut

Switch to the next active program.

Alt+Tab

Switch to the previous active program.

Alt+Shift+Tab

Move the active cursor to the next document.

Alt + Right arrow OR Ctrl+F6 OR Ctrl+Tab

Move the active cursor to the previous document.

Alt + Left arrow OR Ctrl+Shift+F6 OR Ctrl+Shift+Tab

Show the Windows Start menu.

Ctrl+Esc

Close the active document pane

Ctrl+W

Toggle between the active document and the most recently active modeless Alt+F6 dialog box. If no modeless dialog boxes are open, the shortcut has no effect. Cycle through the active document and any open modeless dialog boxes. Alt+Shift+F6 If no modeless dialog boxes are open, the shortcut has no effect.


118 | XMetaL | Keyboard shortcuts

Navigating in a dialog box These shortcut keys enable you to select and use dialog box controls (controls are groups of one or more related objects, such as a push button, or a group of radio buttons). Action

Shortcut

Switch to the next tab in a tabbed dialog box

Ctrl+Tab OR Ctrl+Page Down

Switch to the previous tab in a tabbed dialog box

Ctrl+Shift+Tab OR Ctrl+Page Up

Move to the next control

Tab

Move to the previous control

Shift+Tab

Move to control

Alt + underlined letter

Move between options in the selected drop-down list box

Arrow keys

Move between radio buttons in selected group

Arrow keys

Perform the action assigned to the selected button

Space bar OR Enter

Turn selected check box on or off

Space bar

Turn any check box on or off

Alt + underlined letter

Move to an option a selected drop-down list box

First letter in option name

Open selected drop-down list box

Alt + Down arrow

Close selected drop-down list box

Esc

Perform the action assigned to the default button in the dialog box (if no other push button is selected)

Enter

Select a folder in a folder list

Arrow keys

Update the files visible in the Open or Save As dialog box

F5

Cancel the command and close the dialog box

Esc


XMetaL | Introduction to DITA | 119

Introduction to DITA DITA stands for ‘Darwin Information Typing Architecture’. It is an architecture for creating and maintaining information in print and online. Using DITA, you can deliver content to multiple channels. DITA architecture is extensible, which means that you 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, online help systems, web sites, quick reference, and more. Content that is authored using the DITA architecture is easily reused and repurposed because of its high degree of granularity, that is, the small size of each piece of information. The underlying paradigm for DITA is that content is encapsulated in topic-sized chunks. Authoring content using DITA is a familiar process for authors, because all document components are available in the XMetaL interface.

Topics Topics are units of information that are meaningful when they stand alone. In DITA, topics are structured by topic 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. For example, only task topics can contain step results (created by the stepresult element), and a step result can appear only as part of a step. This architecture creates a standard structure for information that you can use to easily create consistently organized content. However, before you begin authoring, you need to identify the purpose of the information in order to create the correct content type. Many teams adopt XML and DITA because they want to reuse content rather than rewriting the same content slightly differently for each deliverable. For example, you may need an online Help system that contains most of the information that is in a user guide in PDF format. Instead of having to write, edit, review, publish, and translate that information again, you can use the same topics in both deliverables. The key to successfully implementing 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 when starting to author topics is to change your mindset from writing a deliverable, such as book or chapter, to writing a topic. This may be a challenge for authors who are used to writing in an unstructured environment


120 | XMetaL | Introduction to DITA

in which they simply type the content without considering its purpose. In topic-based authoring, you first identify the purpose of the information, pick the appropriate topic type, and only then do you start writing the content. Another challenge is remembering that a topic could appear anywhere, in any deliverable. Because a topic is designed to be a self-contained unit of information, you must be careful not to include contextual information that limits the topic for use in only a specific deliverable. For example, when writing a chapter, you might have written 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 not include the context-specific information about where the database information is located.

Topic structure Althought 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. DITA also supports alternative titles for display as navigation titles and in search results. You may need to specify a 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 in search 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-generated links 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 and keywords 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 include some standard information in each type. Concept and reference topics have the most flexibility in what elements you can include and where. For example, concept topics usually include sections, paragraphs, bulleted lists, and images. Reference topics usually contain tables.


XMetaL | Introduction to DITA | 121

By contrast, the task topic type is restrictive because it allows only one set of steps and prescribes an order in which you can use the elements. For example, you cannot have a result element before the steps. This helps you author information more easily and is intended to follow the logical flow of information.

Maps Maps 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 list include a topicref element in the map that identifies the topic. You can control whether the topic is listed in the 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 include the same source content in multiple deliverables. For example, you can create a map file that organizes the topics for an online Help system. You can then create another map file that uses many of the same topics as well as additional topics to generate a PDF file. Because you can use the same topics and do not have to 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 set of topics that you want to use together. Instead of having to create a single map and add all the topics, you can create a master map and add references to each of the other maps. This allows you to easily include groups 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 help formats, the DITA Open Toolkit generates links between parent topics and the child topics that they contain in the map. You can control whether these links are uni-directional or bi-directional using attributes in the map. To create non-hierarchical links or links between peer topics, you control the link generation in the map with a relationship table. The table is based on the topic types, with a column for each type.

Relationship tables Relationship tables are a special type of table where the columns define the topic type and the rows define the relationship between the topics. Structure Relationship tables organize <topicref> elements by topic type to generate links between the topics. The columns 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 unidirectional or that only appear in one topic in a row and not in the others.


122 | XMetaL | Introduction to DITA

Benefits One key benefit of using a relationship table to generate links between topics rather than specifying the links in each topic file is that you can easily find and maintain all the links between topics because they are stored in one file, the map file. If the file name changes for a topic, you open the map file and update all the references to the file in a single location; you do not have to edit each file that links to the topic. This is especially useful when you are troubleshooting links when generating a deliverable.

DITA references You can access DITA reference information and sample files through the Help menu. Table 9: Supporting documentation Publication

Description

XMetaL Evaluation Guide

Covers basic information about creating DITA topics and maps as well as background information about structured authoring and the advantages of using DITA.

DITA Language Reference

Describes the purpose of each DITA element and the rules associated with it.

DITA Architectural Specification

The OASIS DITA specification. Describes DITA markup, processing, and specialization. Also provides background information on terminology and the DITA DTD/schema.

DITA Open Toolkit User Guide

Describes the Java-based implementation of the OASIS DITA specification, including processing targets such as HTML and PDF.


XMetaL | Authoring DITA content | 123

Authoring DITA content Authoring content using DITA is a familiar process for authors, because all document components are available in 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. Elements and 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 topic You can create a new topic using the standard XMetaL file creation steps. 1. Click File ➤ New. 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 section Sections let you organize the information within a topic. Sections cannot be used to represent a hierarchy within 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 subtopic You can add a new subtopic to the topic you are currently working in. New subtopics are inserted nested inside 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.


124 | XMetaL | Authoring DITA content

• •

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 paragraph The 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 element You 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 invalid location. If the element you select is not valid at the current location, it is inserted at the next valid location in the 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 location in 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 element You 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 frequently used 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.


XMetaL | Authoring DITA content | 125

Insert a multimedia object You can insert multimedia objects in your DITA topic. 1. Click Insert ➤ Object. 2. Choose the object you wish to insert.

Insert a list of steps You 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. 2. Do one of the following: • •

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 component Task 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 links Cross-references and related links provide a way to direct readers to additional information. This information can 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 help system, 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 end of topics. You can insert a link by clicking Insert ➤ Link and choosing a link type. Table 10: Link types Name

Description

Element

Cross-reference

Specify a location within the <xref> current topic, another DITA topic, or a location within another DITA topic

Attribute

Default value

href

the target element

type

the type of the target element, e.g., fig, table


126 | XMetaL | Authoring DITA content

Name

Description

File reference

Web link

Related link to topic

Related link to Web page

Related link to File

Element

Specify a file on your file <xref> system or content repository

Specify a URL or e-mail address

Specify a DITA topic

Specify a Web page or email address

<xref>

<link>

<link>

Specify a file on your file <link> system or content repository

Attribute

Default value

format

dita

scope

local

href

the target element

format

file extension of the target file, e.g., pdf

scope

peer

href

the target element

format

html

scope

external

href

the target element

type

the type of the target element, e.g., fig, table

format

dita

scope

local

href

the target element

format

html

scope

external

href

the target element

format

file extension of the target file, e.g., pdf

scope

peer

Insert a cross-reference When 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 within another 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 refreshed 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 target element type Type a URL

Insert a related link When 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


XMetaL | Authoring DITA content | 127

• •

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 is refreshed 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 references References 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. 1. Do one of the following: • •

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 metadata You can change view and edit elements in the topic prolog using the Topic Metadata dialog. The Normal and Tags On views show the content that would normally appear in output. Metadata is handled through this dialog. The dialog contains most, but not all topic <prolog> elements.Your organization may decide to choose which metadata elements are important to it, and subsequently customize this dialog for more efficient workflow. 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 information on 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 topic You 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. 1. Do one of the following: • •

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


128 | XMetaL | Authoring DITA content

The topic is moved one level up (or down) in the topic hierarchy.

Editing properties You can edit most elements through the Edit Properties dialog. Some of these editing dialogs also let you apply conditions. To edit

Do this

Elements

Select or place the cursor in the element you wish to edit and click Edit ➤ Element Properties

Topic metadata

Click Insert ➤ Topic Metadata

Tables

Place the cursor in the table you wish to edit and click Table ➤ Table Properties

Index markers

Select or place the cursor in the index entry you wish to edit and click Edit ➤ Element Properties

Creating indexes You 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 terms that 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 to insert one index marker at the beginning of the discussion to indicate the start of the range, and one at the end 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 Use this option

To do this

Sort as

Specify alternate sorting for the term

Refer to another index term

Create an index term that refers to another index term

Page range

Specify a page range for the current index term


XMetaL | Authoring DITA content | 129

A complex index The following printed index illustrates the scope and complexity of the indexing options available. Here you see simple terms, parent-child terms, alternate sorting, ‘See’ and ‘See also’ terms, and page ranges. Creating page ranges requires two index markers. The index 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 an alternate sorting. Therefore, ‘Endopterygota’ and ‘Entomology’ appear between ‘E*Kennel’ and ‘E*Terrarium’.

Insert an index marker You 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 the Index entry field. 3. Specify options as required.


130 | XMetaL | Authoring DITA content

• • •

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.


XMetaL | Re-using content | 131

Re-using content You can re-use content within and among documents using the conref attribute. This feature is useful for boilerplate 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 the current 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 created and saved as a reusable component. If you insert as linked content, the element specifies a conref attribute and includes any child elements that are necessary for the document to be valid. You can refresh the reference at a later time. If you insert a copy, the element and its content is copied into the document just as if 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 conref attribute 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 outside of the current element, either within the same file or in another file. Referenced content is specified by the conref attribute. Local content (referred to as ‘placeholder’ in the DITA Architectural Specification) consists of a parent element and any child elements necessary to maintain validity in the source document. It includes the text, attributes, and other elements that you create during the authoring process and is stored within the parent element. In Normal or Tags On view you can choose to display the local content or the referenced content. When you generate output, local content is replaced with referenced content. Example The following file contains a section (‘Canines’) that specifies local content and referenced content from another file. <!-- file: animals.dita --> <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"> <!-- local content --> <title>Canines</title> <p>Here is everything you need to know about dogs.</p> </section> ... <!-- file: animals_for_children.dita --> <concept id="animals_for_children"> <title>Animals for children</title> <conbody> <section id="doggies">


132 | XMetaL | Re-using content

<title>Doggies</title> <p>Doggies are cute and playful.</p> </section> ...

Displaying reusable content When you open a file, referenced content is displayed according to the refresh content preferences you have set in your DITA options. If you have your DITA options set to refresh references when opening a topic or map, referenced content is displayed. If you do not have your DITA option set to refresh references, click Edit ➤ Refresh All References to refresh and display all referenced content. You can show or hide individual reusable components or content references by clicking Reuse ➤ Show Local 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 minitemplate contains a parent element and any child elements that are necessary for the document to be valid as 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 checked for 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 is checked to ensure that it is valid in the current context. Content references must conform to the following requirements: • The target file specified must exist


XMetaL | Re-using content | 133

• 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 generalizable 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. These operations 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 and content references by clicking Edit ➤ Refresh All References. When you refresh references, the latest version of all referenced content is displayed. Local content is not overwritten. You can refresh individual reusable components or content references by clicking Reuse ➤ Refresh and Show 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 ➤ Detach Content Reference. This removes the conref attribute from the parent element and the referenced content can no longer be displayed.

Generalizing elements with content references Using the Insert Element with Content Reference or Insert Reusable Component commands, when you attempt to insert a specialized element that is not in the current content model, XMetal inserts a generalized element 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, XMetaL inserts an <ol> (ordered list) element. This is because <ol> is the parent class of <steps> and it is valid within a Reference topic, whereas <steps> is not. The original (specialized) element names are visible when referenced content is displayed. This behavior is consistent with rules for generalizing content references as specified in the DITA Architectural Specification and the DITA Open Toolkit User Guide.

Create a reusable component When you create a reusable component, you save the selected element(s) in a separate file.


134 | XMetaL | Re-using content

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 multiple elements, they must be contained within a single parent element. Therefore, if you need to reference several block elements that do not have a common parent, you will need to create multiple reusable components. 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 select this option, XMetaL creates a conref attribute on the current element and assigns a value to it. The value contains the ID of the reusable component. The contents of the current element are replaced with the element’s mini-template. 4. Click Continue and save the component.

Insert a reusable component You 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 is also inserted as local content. Because the referenced content is not stored locally, the most recent version 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 not created. Because the content is stored locally, the copied content will not change when the original content is modified.

Insert an element with a content reference You 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 you want to reference. 3. Choose an element. You can preview the content in Page Preview (styled) or Plain Text view before you insert it.


XMetaL | Re-using content | 135

Attach a content reference to an element You can specify a conref attribute on an element you have already created through menu commands or through the Attribute Inspector. 1. Place your cursor inside the element to which you want to attach a content reference. 2. 3. 4. 5.

Click Reuse â&#x17E;¤ Attach Content Reference. If the local element specified is not the one you want, select an element from the dropdown list. Select the file that contains the element you want to reference. 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 â&#x17E;¤ Detach Content Reference.


136 | XMetaL | Working with DITA maps

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 in the 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 inserting topics into your map, you may want to organize them into groups of related topics. Topic headings serve as containers 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-created map 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 you switch to XML view, you can view the map and fix validity problems.

Create a map You can create a new map using the standard XMetaL file creation steps. 1. Click File ➤ New. 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.


XMetaL | Working with DITA maps | 137

Create and insert a topic You can create DITA topics at the time they are added to the map. 1. 2. 3. 4. 5.

In the Map Editor, click Insert ➤ Topic Reference. Enter a topic title. This is the text that appears as the title of the newly created topic. Click Create. Select a DITA Topic or DITA Map template and click OK. 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. 2. Do one of the following: • •

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 link You 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.


138 | XMetaL | Working with DITA maps

Insert a map reference If 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 reference Navigation 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 heading When inserting topics into your map, you may want to organize them into groups of related topics. Topic headings serve as containers for those groups of related topics. You can create these headings at any time and 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 Relationship Table. 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.


XMetaL | Working with DITA maps | 139

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 the editor menus.


140 | XMetaL | Working with DITA bookmaps

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 a comprehensive 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 metadata through the Element List. In addition to bookmap-specific components, you can also insert DITA map components such as topics, topic headings, and topic groups into your bookmap. Generated components Some components act as placeholders and are generated when you create output. This is generally the case for 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 bookmap You can create a bookmap using the standard XMetaL file creation steps. XMetaL displays the bookmap in XML view in the document window. The tabbed interface lets you navigate between open bookmaps. 1. Click File â&#x17E;¤ New. 2. Click the DITA Map tab and choose the DITA bookmap template.

Insert bookmap metadata You 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.


XMetaL | Working with DITA bookmaps | 141

Open a component 1. In the XML view of the bookmap, place your cursor in the component you want to open. 2. Click Reuse â&#x17E;¤ Open Referenced File.

Create and insert a chapter, appendix, or part 1. 2. 3. 4. 5.

In the XML view of the bookmap, place your cursor where you want to insert a chapter, appendix, or part. Click Insert and select Chapter Reference, Appendix Reference, or Part Reference. Type a title, click Create, and select a DITA Topic or Map template. Select a DITA Topic or DITA Map template. 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. 2. 3. 4.

In the XML view of the bookmap, place your cursor where you want to insert a special topic. Click Insert and select Abstract, Draft Introduction, Notices, Dedication, Colophon, or Preface. Type a title, click Create, and select a DITA Topic or DITA Map template. Type a name for the file and save.

Create and insert a booklist Book 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 Figures List, 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 not need to create a topic reference for them. 4. Select the new booklist and click Edit â&#x17E;¤ Element Properties. 5. Type a title, click Create, and select a DITA Topic or DITA Map template.


142 | XMetaL | Working with DITA bookmaps

6. Type a name for the file.

Create and insert a glossary You create glossary terms and definitions in a single file or group of files. Your bookmap can contain one or more glossary files. XMetaL provides templates for creating single or multiple glossary entries. Glossary terms 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 list using 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.


XMetaL | Publishing documents | 143

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 deliverable type. A deliverable type specifies an output format and additional configuration settings. For example, you can apply your own CSS stylesheet to change the appearance of HTML output files. Deliverable types also support conditional 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 Configure Output Options dialog. The output format specified for a deliverable type is indicated in the Edit Deliverable Type dialog. Table 12: Deliverable types Name

Description

XMetaL Enhanced PDF via RenderX XEP

Produces production-quality print output out of the box using XEP and a fully configurable set of parameters.

XMetaL Enhanced PDF via RenderX XEP and Acrobat Distiller

Produces production-quality print output out of the box using XEP and a fully configurable set of parameters. Also includes support for EPS graphics. Requires purchase and installation of Adobe Acrobat Distiller.

HTML Help (CHM)

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.

Single HTML file

Produces a single HTML file with a linked table of contents. Includes support for custom CSS, header, and footer files. The ‘Single HTML File (example)’ deliverable type contains specific CSS, metadata, header, and footer files. You can modify these files to produce custom output.

Multiple HTML files

Produces an HTML file for each topic reference and a root HTML file for the map. Includes support for custom CSS files and header/footer files.

Preview options Preview options let you specify a deliverable type for previewing content. When you select View ➤ Page Preview, 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 Output Log. 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 parameter as follows: cmd_always_open = yes


144 | XMetaL | Publishing documents

XMetaL Enhanced deliverable types You can generate production-quality print output out of the box using the ‘XMetaL Enhanced PDF via RenderX XEP’ and ‘XMetaL Enhanced PDF via RenderX XEP and Acrobat Distiller’ deliverable types.You can customize the 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. They have also been tested with Antenna House XSL Formatter. They are optimized to produce book-type deliverables that include book lists such as a table of contents and index and book divisions such as parts and chapters. The XMetaL Enhanced deliverable types feature processing improvements over previous print deliverable types and the default toolkit ‘PDF2’ output. For example, the <booktitlealt> and <bookpartno> appear as the 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, definition lists, 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 gray background. 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 from the authoring interface through easy-to-understand menus and dialogs. Authors can preview output to see how changes affect output. • Ease of configuration and troubleshooting. XMetaL includes a default set of deliverable types for the various output formats supported by the toolkit. Authors can easily change and add new deliverable types. Administrators can deploy custom deliverable types across an authoring team. Authors can configure output using conditions to produce, for example, an audience-specific deliverable. Processing errors are easily identified by formatting in the output log. • Single HTML file output format. From your map, you can create a single HTML file that includes a table of contents. The ‘Single HTML file (example)’ deliverable type demonstrates custom styling, and headers and footers. • Glossary merging and sorting. Glossary entries are merged from multiple sources and, in the XMetaL Enhanced deliverable types, sorted according to the language specified. • Technical support. Customers can contact XMetaL Technical Support for assistance with configuring the DITA Open Toolkit. Support policies are available from the XMetaL website. • Improved documentation. Detailed documentation on how to customize PDF, HTML, and CHM output is provided.


XMetaL | Publishing documents | 145

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 Toolkit The DITA Open Toolkit is a Java-based implementation of the OASIS DITA Technical Committee’s specification for 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 are posted to the DITA Open Toolkit project page. You can download and install new versions of the DITA Open Toolkit. In order to take advantage of the new version when you generate output, you need to specify it as a parameter in XMetaL. You may also need to re-install other configuration files (for example, those used by RenderX). 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 Toolkit You 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 options You 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 DITA Open Toolkit User Guide. Note: This option is recommended for advanced users who are familiar with the DITA Open Toolkit and XSL.


146 | XMetaL | Publishing documents

To specify

Do this

Global options

Click Tools ➤ Configure Output. Click the Advanced tab. The settings you make here apply to all deliverable types.

Local options

Click Tools ➤ Configure Output. Select a deliverable type and click Edit. Click the Advanced tab. The settings you make here apply to the selected deliverable type only.

You can specify additional parameters as name/value pairs in the Other Output Parameters box.

Specifying a language The language specified for your map or bookmap is used by processors such as the DITA Open Toolkit to determine 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 of the Properties dialog. You can also set the value for xml:lang through the Attribute Inspector. This value takes priority over other language settings. 2. As a property of a component of a map or bookmap, such as a <glossarylist> element. The Language property 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 not specify 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.

Chunking Chunking refers to how the content you see in XMetaL is organized in files when you generate output from a DITA map. By default, the structure of the output from a DITA map reflects that which is represented in the Map Editor or 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 a map


XMetaL | Publishing documents | 147

Set chunking You can change the way content is chunked (divided or merged into new output documents) by setting the chunk attribute. You can specify chunking behavior on most map elements. The value of the chunk attribute consists of one or more space-delimited names. 1. Select an element in the Map Editor. 2. Click Edit â&#x17E;¤ 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 output Some 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 the appropriate compiler in order to generate output. Format

Software

HTML Help

HTML Help Workshop. Contains viewer and compiler. Available for download from the Microsoft Developer Network.

JavaHelp

JavaHelp viewer. Distributed as part of the JavaHelp 2.0 platform. Available for download from Sun Microsystems.

Eclipse Help

Eclipse viewer. Distributed as part of the Eclipse platform. For information about deployment options, see IBM Developer Works.

Create a deliverable type You can create a new deliverable type that specifies an output format and other settings. 1. Click Tools â&#x17E;¤ 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 install the compiler in order to be able to generate output using the deliverable type. For example, you must install 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 file format extension (for HTML) and related links (for PDF).


148 | XMetaL | Publishing documents

Edit a deliverable type You can edit a deliverable type through the Edit Deliverable Type dialog. 1. Click Tools ➤ Configure Output. 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 your output folder, click Specify a folder and select a folder. Deliverable type

Options

Multiple HTML files, Single HTML file

You can specify a custom stylesheet and header and footer files. You can choose an extension for output files.

HTML Help (CHM)

You can specify an alias and map file.

XMetaL Enhanced PDF

You can choose to show related links in output.

4. Optional: Click the Advanced tab and specify advanced options.

Set preview options 1. Click Tools ➤ Configure Output. 2. Click the Preview tab. 3. Select a deliverable type for previewing DITA topics and maps.

Generate output You can generate output for a DITA topic or map in any of the supported output formats. Output specifications are 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, missing images) by clicking File ➤ View Output Log.

Extending your publishing options XMetaL Author provides a flexible framework for publishing DITA documents using the DITA Open Toolkit.


XMetaL | Publishing documents | 149

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 print formatter. A print formatter is a third-party tool that renders XML content as PDF. Each output format specifies a transformation type (transtype) that contains Java and XSL processing. Some transformation types are native to the DITA Open Toolkit and some are supplied by XMetaL. Transformation types are specified in the publishing configuration files. Adminstrators may want to override the settings in the output formats or specify new output formats. Consider the 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 to corporate style guidelines. • Your organization needs to support additional targets as provided by new DITA Open Toolkit plug-ins. For example, 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 configuration file. Table 13: Output formats Name

Notes

PDF via FO with default processing

Basic PDF output. Uses the DITA OT ‘pdf’ transtype.

Book via RenderX

Enhanced PDF output using XEP. Includes improved pagination, indexing, and table layouts. Also referred to as the ‘Idiom plug-in’ or ‘Idiom FO 1.1’ in the DITA Open Toolkit documentation. Uses the DITA OT ‘pdf2’ transtype.

XMetaL Enhanced PDF via RenderX XEP

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 Antenna House XSL Formatter

Enhanced PDF output using XSL Formatter and a fully configurable set of parameters. Requires purchase and installation of Antenna House XSL Formatter. Uses the XMetaL ‘pdf3’ transtype.

XMetaL Enhanced PDF via RenderX XEP and Acrobat Distiller

Enhanced PDF output using XEP and a fully configurable set of parameters. Includes support for EPS graphics. Requires purchase and installation of Adobe Acrobat Distiller. Uses the XMetaL ‘pdf3’ transtype.

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


150 | XMetaL | Publishing documents

Table 14: Print formatters Name

Description

Apache FOP

Provides support for the Basic conformance level in XSL-FO.

RenderX XEP

Provides support for the Extended conformance level in XSL-FO. This includes improved pagination, indexing, and table layouts.You can set configuration options, such as fonts and languages, through the RenderX Assistant. The Assistant is available through the Edit Deliverable Type dialog. Distributed under license.

Antenna House XSL Formatter

Provides support for the Extended conformance level in XSL-FO. This includes improved pagination, indexing, and table layouts.

Publishing configuration files The 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 the batch by setting parameters. These values are used by the DITA Open Toolkit when generating output. Table 15: Publishing configuration files Name

Description

..\XMetaL\Author\DITA\XACs\shared\renditions\ print_dita12.xml

Contains parameter settings and batch code for output formats.

The <globals> element contains parameters that apply to all output formats. The <config> elements contain parameters for specific output formats. ..\Documents and Settings\<user_name>\Application Data\SoftQuad\XMetaL\5.0\ print_local.xml

Contains parameter settings for deliverable types.

The <globals> element contains parameters that apply to all deliverable types.The <config> elements contain parameters for specific deliverable types. These settings override parameters of the same name in print_dita12.xml. The <base_config> ID attribute references a <config> element (that is, an output format) in print_dita12.xml

Specifying parameters You can change the way you generate output, including the appearance of your output deliverable, by specifying parameters. You can specify parameters either by setting options in fields and checkboxes or by typing. Parameters can be global or local. Your settings are stored in the publishing configuration files. To specify

Do this

Global parameters

Click Tools â&#x17E;¤ Configure Output. Click the Advanced tab. The settings you make here apply to all deliverable types.

Local parameters

Click Tools â&#x17E;¤ Configure Output. Click Configure Output. Select a deliverable type and click Edit. Click the Advanced


XMetaL | Publishing documents | 151

To specify

Do this 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 User Guide. 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 ➤ Configure Output. Then select your deliverable type and click Edit. Table 16: Parameter sets by output format Java

Ant

Multiple XHTML files

HTML Help (CHM)

PDF via FO with default processing

Structured FrameMaker

JavaHelp

XMetaL Enhanced PDF via RenderX XEP

Eclipse Help

XMetaL Enhanced PDF via Antenna House XSL Formatter

Eclipse Content

XMetaL Enhanced PDF via RenderX XEP and Acrobat Distiller

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 of name/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


152 | XMetaL | Publishing documents

Note: Ant parameters may contain more than one segment (denoted by the ‘.’ character).

Creating and modifying output formats There may be cases in which you need to create or modify an output format to support new requirements for deliverables. 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. For example, you may wish to create an output format that supports a new FO processor for enhanced PDF output. Once you have created a new output format, you can distribute it to other users in a publishing configuration file.

Create an output format You can create a new output format by creating an XML configuration file and saving it in the same folder as print_dita12.xml. You can distribute new configuration files in order to give all users access to the new output 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 in the new configuration file. You may wish to choose a configuration that has settings similar to those you wish to use in the new configuration. For example, if your new configuration is based on HTML Help (CHM) output, copy and paste 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 format To modify an output format, change the contents of print_dita12.xml, the publishing configuration file that contains 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.


XMetaL | Publishing documents | 153

3. Add new parameters or change settings for existing parameters. Parameters are specified in <instruction> elements.

Troubleshooting When 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 by a yellow box and errors and warnings are surrounded by a red or orange box. You can jump to the next or previous 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 to generating 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 currently generating 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 that you have included the following parameter in your deliverable type: ‘DSDK_PARAM_ditaext = .dita’ (for output formats that use Java) or ‘ANT_PARAM_dita.extname=.dita’ (for output formats that use Ant) and re-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 not be 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 may cause 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 spaces or punctuation.


154 | XMetaL | Working with conditions

Working with conditions In DITA, you can create versions of your content without having to maintain more than one set of source content 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 by using the otherprops attribute. You can use this set of conditions to support the workflow required by your organization. For example, you may have some content intended for administrators, other content intended for users, and content intended for both audiences. By using conditional text, you can indicate which sections of your content is intended for each of the audiences.You can style your conditions so that conditional content is easy to identify. You can specify which conditions to include in your output through the Generate Output dialog. If you specify multiple 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 condition is 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 XMetaL interface. <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 need to 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 configuration file. The name attribute value must be a valid conditional processing attribute name as defined in your DITA DTDs. The following example uses a value of ‘otherprops’ to create a condition called ‘Release’ and the values ‘Beta’ and ‘1.0’. <attribute name="otherprops" title="Release"> <value name="beta" title="Beta" /> <value name="1.0" title="1.0" /> </attribute>


XMetaL | Working with conditions | 155

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 portion of 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 the Administrator check box. You can click more check boxes to specify multiple conditions.

Display conditions in previews or output Within a deliverable type, you can specify all of the conditions you wish to see when you preview content or generate output. Advanced options let you export your settings to a DITAVAL file or to use another DITAVAL file. DITAVAL files are stored in ..\XMetaL\Author\DITA\XACs\shared\renditions\filters. 1. Open a DITA map file. In the Map Editor, select File ➤ Generate Output For DITA Map. Select a deliverable type and click Show/Hide Conditional Text. Expand the list of attributes you want to show or hide conditional text for (e.g., Audience). For each value, indicate whether you want it to be visible. If the check-box is checked, then all conditional text 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. 2. 3. 4. 5.

Style a condition You 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


156 | XMetaL | Working with conditions

Modify conditions To modify conditions, you can customize the values for the Audience, Platform, or Product conditions or you can 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. 3. Do one of the following: â&#x20AC;˘ â&#x20AC;˘

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>


XMetaL | Working with DITA specializations | 157

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 default style sheets to add or change formatting for base DITA elements and your specialized elements. The steps are similar to those for creating an XMetaL customization. To take advantage of the formatting and customization 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\Common Files\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 added to catalog-dita.xml and/or catalog-dita_template.xml. Since catalog files denote paths in a manner relative 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 can be formulated easily from demo specialization examples, which have relative path system IDs that resolve to 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.


158 | XMetaL | Working with DITA specializations

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 reusable components 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 template Once you have configured XMetaL, you can create a template so that authors can create new documents using 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 Attribute Inspector. 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 the system 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, and ditaarch:DITAArchVersion. 8. Save the file with the extension ‘.xml’, ‘.dita’, or ‘.ditamap’ in your DITA templates directory, specifying UTF-8 encoding type. Test your template by clicking File ➤ New.


XMetaL | Working with DITA specializations | 159

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 example element. (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 formatting You 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 rule to 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 CSS file

Location

Specifies

ditabase-base.css

..\XMetaL\Author\XACs\shared

Baseline CSS styles for ditabase elements such as "topic/topic" and "topic/p"

ditabase-base-override.css

..\XMetaL\Author\DITA\XACs\ditabase Overriding CSS styles for re-style ditabase elements such as "topic/topic" and "topic/p"

ditabase-derived.css

..\XMetaL\Author\DITA\XACs\shared

Baseline CSS styles for ditabase elements such as "task/task" and "reference/reference"


160 | XMetaL | Working with DITA specializations

CSS file

Location

Specifies

ditabase-derived-override.css

..\XMetaL\Author\DITA\XACs\ditabase Overriding CSS styles for re-style ditabase elements such as "task/task" and "reference/reference"

{$specialized_dtd}_ditabase-spe-

..\XMetaL\Author\DITA\XACs\{$spe-

Specialized CSS styles for specialized

cialized.css

cialized_dtd}

elements such as "faq/faq"

Changing the display font size You can change the size of the display font. For example, to increase the default font size of a document, type the following in ditabase-base-override.css: $DOCUMENT { font-size: 18px; }


XMetaL | Working with a content repository | 161

Working with a content repository XMetaL Connector is a repository integration layer that provides rapid access to your content repository through an adapter, which is a software driver for your particular repository. The adapter provides access to repository operations, such as opening files and check in/check out operations, through XMetaL dialogs and menus. The adapter is provided and installed by a system administrator. Note: The availability of repository functionality is determined by the adapter. Refer to your repository documentation for details. Table 18: Common repository operations To do this:

Click this:

Notes

Open a document that you have checked out

Repository ➤ Open Checked-Out Document

Explore a repository

Repository ➤ Explore Repository

Check in a document

Repository ➤ Check In Document

Check out a document

Repository ➤ Check Out Document You may check out a document only if it is currently open for viewing. When you check out a document, the current view of the document is replaced with the latest version of the document.

Undo checkout of a document

Repository ➤ Undo Checkout

View document or map properties

Repository ➤ Document Properties

Set the URL for the default repository

Repository ➤ Repository Options

Log on to a repository

Repository ➤ Log On to Repository Some repositories require that you log on before any repository operations are allowed.

Log off from a repository

Repository ➤ Log Off from Repository

You may check in a document only if it is currently open for editing.

The document reverts to its previous version.

You must set the URL for the repository before accessing files for the first time or if you switch repositories.

Open a repository map or topic file When you open a DITA-based repository map file, you have the option of downloading all referenced components (for example, reusable components). You may wish to do this in order to improve performance. 1. Do one of the following: • •

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.


162 | XMetaL | Working with a content repository

Create a new repository file The preferred method of creating a new repository document is by using a repository template. When you add referenced components (for example, images and links) to the new file, you will have access to repository-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 toolbar You can access and manage documents in a repository through the repository toolbar. Table 19: Repository toolbar commands Button

Name/Tooltip

Menu command

Description

New from Repository Template

Repository ➤ New from Repository Template

Displays repository contents

Open from Repository

Repository ➤ Open from Repository

Displays repository contents

Explore Repository

Repository ➤ Explore Repository

Displays a search dialog

Check In Document

Repository ➤ Check In Document

Displays repository contents

Check Out Document

Repository ➤ Check Out Document

Displays repository contents

Undo Checkout

Repository ➤ Undo Checkout

Reverts to previously saved version of the document

Document Properties

Repository ➤ Document Properties

Displays information about the current document


XMetaL | Working with a content repository | 163

Adapter configuration file Configuration files are located at ../XMetaL/Author/CRCL/configs. Each adapter instance must have a configuration file. Note: Only one configuration file can have the AdapterInstance default attribute set to True.


164 | XMetaL | Working with XMetaL Reviewer comments

Working with XMetaL Reviewer comments If you load a document that has been exported from XMetaL Reviewer, XMetaL Author identifies the document as 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 1. Do one of the following: •

If you know the approximate position in the document, you can search for the comment icon in the document pane. Click on the icon to select the comment in both the document pane and the Resource Manager. If you know some of the text in the comment itself, you can search for the comment text in the Resource Manager.

Filter comments 1. Click View ➤ Filter Comments. 2. Select options as required.

Integrate revisions If 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.


XMetaL | Appendix A: Configuring XHTML and CHM output | 165

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 Cascading Style Sheets (CSS). You can also specify custom headers and footers in separate HTML files. You can save these and other settings in an XMetaL deliverable type. CSS files

Specify the appearance of HTML pages, including fonts, colors, margins, and padding. XMetaL Author includes default CSS files.

Headers and footers

Specify the header and footer content of every HTML page. You can create headers and footers in separate HTML files. The content of these is copied into your HTML output.

XMetaL deliverable types 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 according to their output format (for example, ‘Multiple HTML files’). 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 includes selectors and styles for left-to-right output. • C:\Program Files\Common Files\XMetaL Shared\DITA_OT\resource\commonrtl.css .This file includes selectors 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 to this file. You can copy and edit this file to create custom styling for your output. You specify your custom CSS files 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 you create) in a separate folder within the ‘XMetaL Shared’ folder. Name the folder according to the deliverable type. 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 files You can customize the appearance of your XHTML and CHM output files using custom CSS files. Begin by copying the default CSS files.


166 | XMetaL | Appendix A: Configuring XHTML and CHM output

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. <!-- file: C:\Program Files\Common Files\XMetaL Shared\DITA_OT\resource\commonltr.css --> .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: <!-- file: [XMetaL Shared]\xhtml_custom\custom.css .notetitle { font-weight: bold; color: red;}

Note: In your custom CSS file, you need to include only the selectors you are changing or adding. You can delete the remaining selectors. Once you have created your CSS file, you need to specify it in the Edit Deliverable Type dialog. You also need to add the ‘copycss’ parameter so that your custom CSS file is copied to the output folder every time you generate output.

Headers and footers You can create headers and footers for your XHTML and CHM output using separate header and footer files. Header and footer content is created using HTML elements. The header and footer files need contain only a single <div> element and child elements. Tip: You can refer to the <div> class selector in your custom CSS files to provide custom styling for your headers and footers. Use an id attribute on <div> elements to make styling with CSS easier. Your header and footer files are saved in your custom configuration folder. The following is an example of a custom header file: <!-- file: [XMetaL Shared]\xhtml_custom\custom-hdr.html --> <div id="custom-header"> <h3>Acme Industries Help</h3> </div>

The following is an example of a custom footer file: <!-- file: [XMetaL Shared]\xhtml_custom\custom-ftr.html --> <div id="custom-footer"> <p class="copyright-notice">Copyright &169; 2007 Acme Industries. All rights reserved.</p> </div>


XMetaL | Appendix A: Configuring XHTML and CHM output | 167

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, the content of the header and footer files is copied into the HTML output files.

Deliverable types and parameters You specify your custom CSS, header, and footer files in a deliverable type. XMetaL saves the settings you use for generating output as parameters. You specify parameters through the Edit Deliverable Type dialog. The manner in which you specify parameters 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 File

Parameter

Description

Specific CSS

css

Your custom CSS file.

Page header

hdr

The file containing your custom header. The contents of this file are placed immediately after the <body> tag in the HTML output files.

Page footer

ftr

The file containing your custom footer content. The contents of this file are placed immediately before the </body> tag in the HTML output files.

Save settings in an XHTML deliverable type Once you have created your custom CSS and header and footer files, you can specify them in an XHTML deliverable type. 1. Click Tools ➤ Configure Output. 2. Select the ‘Multiple HTML files’ deliverable type and click Edit.


168 | XMetaL | Appendix A: Configuring XHTML and CHM output

3. In the General tab, specify the settings for Specific CSS, Page header, and Page footer by clicking the Browse button.


XMetaL | Appendix A: Configuring XHTML and CHM output | 169

4. Click the Advanced tab and type the â&#x20AC;&#x2DC;copycssâ&#x20AC;&#x2122; parameter in the Other output parameters box as specified below.


170 | XMetaL | Appendix A: Configuring XHTML and CHM output

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 type Once you have created your custom CSS and header and footer files, you can specify them in an HTML Help (CHM) deliverable type. 1. Click Tools ➤ Configure Output. 2. Select the ‘HTML Help (CHM)’ deliverable type and click Edit.


XMetaL | Appendix A: Configuring XHTML and CHM output | 171

3. Click the Advanced tab and type the parameters indicated below in the Other output parameters box.


172 | XMetaL | Appendix A: Configuring XHTML and CHM output

Note: Parameters for this deliverable type use Ant syntax. The paths specify the custom configuration folder 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.


XMetaL | Appendix B: Configuring PDF output | 173

Appendix B: Configuring PDF output You can use XMetaL in conjunction with the DITA Open Toolkit to produce PDF output from your DITA topics and maps. To produce PDF, XMetaL first transforms DITA-based content into an FO file (XML with formatting objects) 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 directory and making changes to the catalog file in that directory. The changes you make override the settings in the default 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 referred to as the ‘Idiom plug-in’ or ‘Idiom FO 1.1’ in the DITA Open Toolkit documentation. This processing uses the DITA OT ‘pdf2’ transtype. Changes that you make to the default pdf2 processing affect all deliverable types that use the ‘Book via RenderX’ output format. The XMetaL Enhanced output formats are a customization of the default toolkit processing. These output formats 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 that use 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:


174 | XMetaL | Appendix B: Configuring PDF output

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 Component

Default file/folder

Custom configuration file/folder

Catalog file

[FO]\cfg\catalog.xml

[FO_CUSTOM]\catalog.xml

Attribute sets

[FO]\cfg\fo\attrs\*.xsl

[FO_CUSTOM]\fo\attrs\custom.xsl

Artwork

[FO]\cfg\common\artwork

[FO_CUSTOM]\common\artwork

Font mappings

[FO]\cfg\fo\font-mappings.xml

[FO_CUSTOM]\fo\font-mappings.xml

Page layouts

[FO]\cfg\fo\layout-masters.xml

[FO_CUSTOM]\fo\layout-masters.xml

XSLT style sheets

[FO]\xsl\fo\*.xsl

[FO_CUSTOM]\fo\xsl\custom.xsl

Variables

[FO]\cfg\common\vars\*.xml

[FO_CUSTOM]\common\vars\*.xml

Index configurations

[FO]\cfg\common\index\*.xml

[FO_CUSTOM]\common\index\*.xml

A custom configuration contains the following components: Catalog file

The catalog file points to the other files in your custom configuration.

Attribute sets

Attribute sets contain formatting information such as fonts, colors, margins, padding, and borders. There are attribute sets for almost every DITA element. They are similar in concept to Cascading Style Sheets (CSS). Two excellent resources are http://www.dpawson.co.uk/xsl/sect3 as well as Mapping of elements to the permitted properties

Artwork

This folder includes images for your customization, such as those used in headers and footers. The accepted image formats are JPEG, GIF or PNG. PDF images can also be used. The default resolution is 120 dpi. See http://www.renderx.com/reference.html#Graphic_Formats for more information.

Fonts

Font files contain font mapping information.

Page layouts

Page layouts describe page characteristics such as dimensions, regions, and margins.

XSLT style sheets

XSLT style sheets contain templates that typically create formatting objects. They are frequently used in conjunction with variables.

Variables

Variables define strings for use in headers, footers, and generated content.

Index configurations

Index configurations control the display of the index, including sort order.

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


XMetaL | Appendix B: Configuring PDF output | 175

• 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 and their 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. <!-- file: [FO]\cfg\fo\attrs\commons-attr.xsl --> <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 create a title page that reflects the graphic standards of your company. Title pages typically contain the document title, product name, and corporate graphics. The following example adds a background image to the title page. <!-- file: [FO_CUSTOM]\fo\attrs\custom.xsl --> <!-- overrides __frontmatter attribute set from [FO]\cfg\fo\attrs\front-matter-attr.xsl --> <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 custom configuration. The (source) path is: [FO_CUSTOM]\common\artwork


176 | XMetaL | Appendix B: Configuring PDF output

The path to the background image in the xsl:attribute is the relative path required by the DITA Open Toolkit. 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. Page masters describe basic page layouts, such as margins and columns. Each page of a document is rendered by 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 a page with a header and footer. <!-- file: [FO]\cfg\fo\layout-masters.xml --> <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 following custom page master modifies the default title page layout: â&#x20AC;˘ the page orientation is now landscape (11 inches wide x 8.5 inches high) â&#x20AC;˘ all margins are set to 0.5 inches <!-- file: [FO_CUSTOM]\fo\layout-masters.xml --> <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>


XMetaL | Appendix B: Configuring PDF output | 177

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, the following attribute sets (‘__body__odd__footer ’ and ‘ __body__odd__footer__pagenum’ ) specify styles for the footer content on odd-numbered pages of the document body. <!-- file: [FO]\cfg\fo\attrs\static-content-attr.xsl --> <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, the following attribute sets style the footer text in italics and the page number as normal text, colored red. <!-- file: [FO_CUSTOM]\fo\attrs\custom.xsl --> <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 other generated content. Variables can be localized, and additional variable files are named according to locale as defined 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 framework for localizing header and footer content.


178 | XMetaL | Appendix B: Configuring PDF output

The following are the default variables used by the toolkit to produce header content for odd-numbered and even-numbered body pages. The even-numbered header contains the product name followed by a running header 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 to process the Body odd header and Body even header variables (see XSL templates on page 178). <!-- file: [FO]\cfg\common\vars\en_US.xml --> <!-- The header that appears on odd-numbered pages. --> <variable id="Body odd header"> <param ref-name="prodname"/>&#xA0;|&#xA0;<param ref-name="heading"/>&#xA0;|&#xA0;<param ref-name="pagenum"/> </variable> <!-- The header that appears on even-numbered pages. --> <variable id="Body even header"> <param ref-name="pagenum"/>&#xA0;|&#xA0;<param ref-name="prodname"/>&#xA0;|&#xA0;<param ref-name="heading"/> </variable>

Custom variables processing The following example contains variables that override the default headers for odd-numbered and evennumbered pages. The even-numbered header contains the page number followed by the product revision code; 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 178 for sample XSL.) <!-- file: [FO_CUSTOM]\common\vars\en_US.xml--> <!-- The header that appears on odd-numbered pages. --> <variable id="Body odd header"> <param ref-name="heading"/>&#xA0;|&#xA0;<param ref-name="pagenum"/> </variable> <!-- The header that appears on even-numbered pages. --> <variable id="Body even header"> <param ref-name="pagenum"/>&#xA0;|&#xA0;<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 and formatting content. Using the default variable definition for headers of even-numbered body pages, the following template is used by the body-even page master to insert the product name, heading, and page number variables. Formatting occurs as a result of the â&#x20AC;&#x2DC;__body__even__headerâ&#x20AC;&#x2122; attribute set. <!-- file: [FO]\xsl\fo\static-content.xsl --> <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"/>


XMetaL | Appendix B: Configuring PDF output | 179

</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. theVariableID

The name of the variable in the locale file (e.g. [FO]\cfg\common\vars\en_US.xml)

theParameters

A set of parameters used by the the locale variable. In the above example, the locale variable is Body even header, which uses the parameters pagenum, prodname, and heading:

<!-- file: [FO]\cfg\common\vars\en_US.xml --> <!-- The header that appears on even-numbered pages. --> <variable id="Body even header"> <param ref-name="pagenum"/>&#xA0;|&#xA0;<param ref-name="prodname"/>&#xA0;|&#xA0;<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 together with custom variable definitions. The following example demonstrates how to create a custom header for even-numbered body pages. The custom 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 template will use. The value of the variable in this example, â&#x20AC;&#x2DC;Body even headerâ&#x20AC;&#x2122;, is computed by two other parameters, pagenum and docrev. These parameters are passed when we call the insertVariable template from the insertBodyEvenHeader template. The pagenum parameter is merely the FO markup required to insert a page number. The docrev parameter makes use of the docRevision variable (see excerpt from [FO_CUSTOM]\fo\xsl\custom.xsl below). <!-- file: [FO_CUSTOM]\common\vars\en_US.xml--> <!-- The header that appears on even-numbered pages. --> <variable id="Body even header"> <param ref-name="pagenum"/>&#xA0;|&#xA0;<param ref-name="docrev"/> </variable> <!-- file: [FO_CUSTOM]\fo\xsl\custom.xsl --> <!-- revision code --> <xsl:variable name="docRevision"> <xsl:variable name="mapDocRevision" select="$map/@rev"/> <xsl:variable name="bkinfoDocRevision" select="/*[contains(@class, ' map/map ')]/@rev"/>


180 | XMetaL | Appendix B: Configuring PDF output

<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> <!-- insertBodyEvenHeader (uses $docRevision) --> <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: <!-- file: [FO_CUSTOM]\fo\xsl\custom.xsl --> <?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 following examples 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 attribute set inherit from this set. Note: Definition lists (<dl> elements) are rendered as <fo:table> elements, so their attributes are included in the table below. Table 22: Default content attribute sets Component

Attribute sets

Default file (in [FO]\cfg\fo\attrs)

Headings

topic.title, topic.topic.title

commons-attr.xsl


XMetaL | Appendix B: Configuring PDF output | 181

Component

Attribute sets

Default file (in [FO]\cfg\fo\attrs)

topic.title__content, topic.topic.title__content section.title, example.title, fig.title Body text

topic

commons-attr.xsl

body__toplevel, body__secondLevel body section p __fo__root Tables

table.title

tables-attr.xsl

__tableframe__top, __tableframe__bottom thead.row.entry, thead.row.entry__content dl dlentry.dt, dlentry.dt__content dlentry.dd, dlentry.dd__content Notes

note

commons-attr.xsl

note__label note__table note__image__entry Lists

ul, ul.li, ul.li__label, ul.li__label__content, etc.

lists-attr.xsl

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 table headings: <!-- file: [FO]\cfg\fo\attrs\tables-attr.xsl --> <xsl:attribute-set name="thead.row.entry"> <!--head cell--> <xsl:attribute name="background-color">antiquewhite</xsl:attribute> </xsl:attribute-set> <xsl:attribute-set name="thead.row.entry__content"> <!--head cell contents--> <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.


182 | XMetaL | Appendix B: Configuring PDF output

In the following example, the background color for table headers is set to black. Table heading text is also customized. <!-- file: [FO_CUSTOM]\fo\attrs\custom.xsl --> <xsl:attribute-set name="thead.row.entry"> <!--head cell--> <xsl:attribute name="background-color">black</xsl:attribute> </xsl:attribute-set> <xsl:attribute-set name="thead.row.entry__content"> <!--head cell contents--> <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 defined for each note type. The following example shows how the note of ‘type=note’ is rendered. <!-- file: [FO]\cfg\common\vars\en_US.xml --> <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 following example shows a note of ‘type=note’ with no preceding text and a custom image. <!-- file: [FO_CUSTOM]\common\vars\en_US.xml --> <variable id="Note"><!-- no image --></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 following template uses a custom attribute set. <!-- file: [FO_CUSTOM]\common\vars\en_US.xml --> <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)">


XMetaL | Appendix B: Configuring PDF output | 183

<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 template applies to topics that have the outputclass attribute value of â&#x20AC;&#x2DC;frontmatterâ&#x20AC;&#x2122;. <!-- file: [FO_CUSTOM\fo\xsl\custom.xsl --> <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. <!-- file: [FO_CUSTOM\fo\xsl\custom.xsl --> <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 templates where you want the default processing. For example, you might want to include images in your front matter using the default placeImage template. <!-- file: [FO_CUSTOM\fo\xsl\custom.xsl --> <xsl:template match="image" mode="frontmatter"> <fo:block> <xsl:call-template name="placeImage" select="." mode="" ><!-- switch to default 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>


184 | XMetaL | Appendix B: Configuring PDF output

Fonts You can control the fonts in your PDF output through attribute sets and the following font mapping files: â&#x20AC;˘ [FO_CUSTOM]\fo\font-mappings.xml. This file maps one or more fonts to a logical font name. â&#x20AC;˘ ..\Program Files\Common Files\XMetaL Shared\renderx\xep.xml. This file maps a font to a file.

Localization Generated 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 configuration framework on page 173. Note: If you are using the XMetaL Enhanced deliverable types (pdf3 transtype), modify the variable files in the following location: C:\Program Files\Common Files\XMetaL Shared\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, comment out the line that deletes the file. <!-- file: ..\DITA_OT\demo\fo\build.xml --> <delete> <fileset dir="${buildDir}" includes="stage?.*"/> <!-- do not delete <fileset dir="${dita.map.output.dir}" includes="topic.fo"/> --> </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 parameters When you use the XMetaL Enhanced deliverable types, you can customize your PDF output by setting parameters. 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].


XMetaL | Appendix B: Configuring PDF output | 185

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 following files and copy them into ..\xsl\custom.xsl: â&#x20AC;˘ [xmfo]\Customization\fo\xsl\xm_static_content.xsl â&#x20AC;˘ [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 margins Page margins set the space from the body content to the physical edge of the page. The top and bottom margin space is used for header and footer content. Table 23: Parameters Name

Description

xm.page.margin.top

The top page margin is the distance from the body content to the physical top edge of the page. This area is used for header content.

xm.page.margin.bottom

The bottom page margin is the distance from the body content to the physical bottom edge of the page. This area is used for footer content.

xm.page.margin.inner

The inner page margin is the distance from the body content to the physical inner edge of the page (where the book is bound ). For single-sided output, set the xm.page.margin.inner value equal to the xm.page.margin.outer value.

xm.page.margin.outer

The inner page margin is the distance from the body content to the physical outer edge of the page. For single-sided output, set the xm.page.margin.outer value equal to the xm.page.margin.inner value.

Example The top, bottom, inner, and outer page margins are, respectively, 1 inch, 1 inch, 0.75 inch, and 0.5 inch. <!-- file: [xmfo]\Customization\fo\attrs\custom.xsl --> <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>


186 | XMetaL | Appendix B: Configuring PDF output

Headers and footers You 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 content of each table cell. The relative widths value for headers and footers table cells must be three integers from 0 to 9, separated by a space. To center text in a header or footer, make sure the first and last table cells are the same, for example, ‘1 5 1’, ‘2 3 2’. Variables depend on your map or bookmap markup. For example, if you do not have author information in your 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 Name

Description

body even header

The header for even-numbered body pages

body odd header

The header for odd-numbered body pages

body even footer

The footer for even-numbered body pages

body odd footer

The footer for odd-numbered body pages

body first header

The header for the first body page in a part or chapter

body first footer

The footer for the first body page in a part or chapter

body last header

The header for the last body page in a part or chapter

body last footer

The footer for the last body page in a part or chapter

Table 25: Variables Name

Description

$xmDocumentTitle

The title of the book

$xmDocumentSubTitle

The subtitle or alternate title of the book

$xmPartTitle

The title of the current part

$xmChapterTitle

The title of the current chapter

$xmTopicTitle

The title of the current topic, concept or reference

$xmPageNumber

The current page number

$xmDocRevision

The revision number of the book

$xmDocAuthor

The author of the book

$xmCopyRightYear

The copyright year

$xmCopyRightHolder

The copyright holder


XMetaL | Appendix B: Configuring PDF output | 187

Footer content customization In the code sample below, the footer for even-numbered pages has the following characteristics: • 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 the footer table cells. The value for __body__even__footer__Cols must be three integers from 0 to 9, separated by a space. In the code sample below, the third column is eight times wider than the first and second columns ('1 1 8') <!-- file: [xmfo]\Customization\fo\xsl\custom.xsl --> <!-- body even footer --> <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. <!-- file: [xmfo]\Customization\fo\attrs\custom.xsl --> <xsl:attribute-set name="__body__even__footer"> <xsl:attribute name="color">red</xsl:attribute> </xsl:attribute-set>

Fonts You can set the font family and size. Table 26: Parameters Name

Description

xm.document.font-size

The base font size for the document. This is the font size that is used by most body content (for example, paragraphs and lists). The value is set in points (pt).

xm.body.font.family

Sets the font body type for body text. Can be set to serif or sans-serif.

xm.title.font.family

Sets the font type for titles. Can be set to serif or sans-serif.


188 | XMetaL | Appendix B: Configuring PDF output

Example The base font size is set to 10 points, the body font is serif, and the title font is sans-serif. <!-- file: [xmfo]\Customization\fo\attrs\custom.xsl --> <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>

Tables You can change the table fonts, background colors, and borders. Table 27: Parameters Name

Description

xm.table.title.font-size

The font size for table titles. The value can be a percentage of the document.font.size value or an absolute value, in points (pt).

xm.table.font-size

The font size for table body content. The value can be a percentage of the document.font.size value or an absolute value, in points.

xm.thead.row.entry.background-color

The background color for table headers. The value can be a color keyword (e.g., blue) or an RGB value (e.g., #0000FF).

xm.table.border.color

The color of table borders. This includes the border around the table, as well as any row and column borders.The value can be a color keyword or an RGB value.

xm.table.rows

Turns row borders on or off. If a table in the document has the rowsep attribute set, then row borders are displayed for that table regardless of the xm.table.rows value. The value can be set to 1 (on) or 0 (off).

xm.table.columns

Turns column borders on or off. If a table in the document has the colsep attribute set, then column borders are displayed for that table regardless of the xm.table.columns value. 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 document.font.size value, a background color specified as an RGB value, and a border color of red. The row borders are displayed; column borders are not displayed. <!-- file: [xmfo]\Customization\fo\attrs\custom.xsl --> <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> <!-- show row borders --> <xsl:param name="xm.table.rows">1</xsl:param> <!-- hide column borders --> <xsl:param name="xm.table.columns">0</xsl:param>


XMetaL | Glossary | 189

Glossary ambiguous content model

A content model in a DTD is ambiguous if an element in a document instance could match more than one part of the content model.

application customization

A customization at the application level. Application-level customizations apply to all documents, regardless of the DTD or schema used.

attribute

A value that is associated with an element but is not part of the content of the element. Many properties are represented by attributes, for example, class or ID.

block element

An element whose content is preceded and followed by line breaks.

browser

A program that communicates with Web servers and is used for retrieving and displaying documents from the World Wide Web or an intranet. Most browsers use a graphical interface to provide access to text, images, audio, and video.

CALS table model

A widely used DTD for table markup, described in the U.S. Department of Defense SGML standard MIL-M-28001B. XMetaL Author supports a definition of the CALS DTD developed by the OASIS consortium and described at www.oasis-open.org.

cascading style sheet (CSS)

A way to specify document formatting that is supported by browsers. XMetaL uses cascading style sheets to format the document pane in Normal and Tags On views. A cascading style sheet generally consists of one or more rules that define element appearance. These style sheets are said to be cascading because several style sheets can be applied to the same document. See www.w3.org for more information.

catalog files

One or more files that map external identifiers for DTDs, rules files, or entities to a filename. Also called OASIS catalog files. For more information on catalog files, see OASIS Technical Resolution 9401:1997.

CDATA

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 documents can contain CDATA sections; SGML documents can contain CDATA elements.

CDATA section

A markup construct in XML and SGML documents, beginning with the characters ‘<![CDATA[’ and ending with ‘]]>’, inside which all content is treated as character data.

chunking

The way in which the content you see in XMetaL is organized in files when you generate output from a DITA map.You can specify chunking behaviors, for example, that split composite topics into several output files.

COM interface

Component Object Model. A language-independent interface developed by Microsoft for combining applications under Microsoft Windows. The XMetal scripting API uses a COM interface.

content model

An expression in a DTD that defines the content of a particular element.

counter

A numerical element prefix that is incremented automatically for each successive occurrence of that element. For example, chapters in a document may be numbered 1, 2, 3, ..., etc. Counters are implemented via a cascading style sheet.

customization

An enhancement to the functionality, behavior, or appearance of XMetaL Author. Customizations can be made at the document level or at the application level.

current element

The element containing the insertion point or selection. If an entire element is selected, the current element is the parent of that element, not the selected element itself.


190 | XMetaL | Glossary

deliverable type

Specifies an output format and additional configuration settings that you supply to the DITA Open Toolkit.

DOCTYPE declaration

Document type declaration. A declaration at the top of an XML or SGML document that specifies which DTD applies to the document, and may contain some extra markup declarations.

document customization

A customization that applies to all documents based on the DTD or schema used for the customization.

Document Object Model (DOM)

The Document Object Model (DOM) is an abstract definition of an API (application program interface) for manipulating XML document structures. The DOM is a Recommendation of the World Wide Web Consortium (W3C), developed and maintained by the W3C DOM Working group. XMetaL follows the DOM Level 1 Specification.The DOM was designed to represent XML structures, but can represent SGML structures (such as CALS tables) if they are also found in XML.

DTD

Document Type Declaration. A set of declarations, written in a formal notation, that defines the structure of a document.

element

The building blocks of XML and SGML documents. Elements are named according to their function in the document, for example, headings, lists, and paragraphs.

empty element

An element that cannot have any content.

entity

A special character, a block of text or markup, or a file.

entity reference

A reference, using a specific syntax, to an entity. When the document is displayed in a browser or editor, the entity reference is replaced by the text or file that the entity represents.

external entity

A type of entity that represents another XML or SGML file.

external identifier

A way of identifying an external file. External identifiers can appear in a document type declaration and in external entity declarations, where they identify the external file that the entity refers to. In SGML files, external identifiers can consist of a system identifier, a public identifier, or both. In XML files, external identifiers must contain a system identifier, which may be preceded by a public identifier.

external identifier map file

The file, ../XMetaL/Author/extid.map, that associates external identifiers with filenames on the system.

followed-by element An element that is inserted following the occurrence of a specific element. Followed-by elements are configured in XMetaL Developer as part of the customization (.ctm) file. form

A data-entry interface usually associated with specific elements in an XMetaL document. Forms are designed in the XMetaL Forms Toolkit (XFT) either as dialog boxes that are launched from an XMetaL macro, or as content that appears as part of an element.

general entity

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, which represent a graphic, audio, or video, etc. file.

generated text

Text that is not part of the document content, but is generated by a display program and displayed at the beginning or end of an elementâ&#x20AC;&#x2122;s content.

graphic entity

A type of general entity that represents an external multimedia file, for example, a graphic, video, or audio file.

hypertext

Text that can be used to link to another document or another location in the same document. The viewer can display the linked document or location by clicking the text.


XMetaL | Glossary | 191

ID

A unique identifier. The value of an ID attribute must not be used for any other ID attribute in the document.

IDispatch object

An object associated with an in-place control that gives a script access to the controlâ&#x20AC;&#x2122;s properties, methods, and events.

IDREF

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.

inline element

An element that does not have a line break before or after its contents.

in-place control

An ActiveX control that is embedded in the Normal and Tags On document panes in XMetaL Author or XMetaL XMAX, and communicates with XMetaL Author or XMetaL XMAX so that changes in the control can modify the document, and vice versa.

internal subset

An optional part of the document type declaration that may contain markup declarations.

ISO

International Organization for Standardization.

ISO 8859-1 character The character set for special or accented characters that is widely used in HTML set documents. This character set is also called ISO Latin 1. It includes characters required for most western European languages. local content

Local content includes the text and other elements that you enter during the authoring process and is stored within the element. Also known as â&#x20AC;&#x2DC;placeholderâ&#x20AC;&#x2122; content.

macro

A sequence of XMetaL actions or script commands that can be run as a unit via a keyboard shortcut, a toolbar button, or a menu item. Macros can be recorded from within XMetaL Author, or created by inserting scripting code into a macro file using XMetaL Developer.

marked section

A markup construct in SGML documents that designates the content for special processing. The parameters of the marked section specify the type of processing. The most common uses for marked sections are to cause a portion of the document to be ignored at certain times, and to surround SGML markup constructs that you want to be treated as text, not markup.

marked section parameter

Keywords that determine how to process a marked section in an SGML document. The available keywords are INCLUDE (process the section normally); IGNORE (do not process the section); CDATA (treat elements and entity references in the content as text, not markup); RCDATA (treat elements in the content as text, not markup); and TEMP (the section is temporary).

markup

Special instructions or indicators in a document that specify how the enclosed content is to be processed by an application. Element tags are an example of markup. In an XML or SGML document, the element tags specify the role of the content (heading, title, paragraph, etc.).

MCR file

A macro file. An MCR file is an XML-based customization file containing XMetaL macros, or scripts. For document-level customizations, the MCR filename is named according to the DTD or schema; for application-level customizations, the MCR filename is xmetal.mcr.

mini-template

The mini-template consists of a parent element and any child elements that are necessary for the document to be valid as well as prompt text. A mini-template is inserted when there is no local content for an element with a content reference.

modal dialog box

A dialog box that remains active until it is closed. Once it is open, you must complete your task and close it before you can return to the main window and continue working.

modeless dialog box A dialog box that can remain open while you are working in the main program window.


192 | XMetaL | Glossary

namespace

A feature of XML that permits documents to contain identically-named elements defined in more than one DTD or schema.

notation

A declaration in a DTD that specifies a file format that can be used for files represented by graphic entities. For example, if GIF files are to be used, a notation declaring the GIF format must be present in the DTD.

OASIS

Organization for the Advancement of Structured Information Standards, a consortium dedicated to promoting structured information standards such as XML and SGML. For more information, see www.oasis-open.org.

output format

Specifies the file format of an output deliverable and, in the case of PDF, a print formatter.

parameter entity

An entity that represents one or more marked section parameter keywords.

PCDATA

Parsed character data. The most common form of text content in XML and SGML documents. In PCDATA text, any markup, such as element start and end tags and entity references, is interpreted with its normal meanings.

pretty-printing

Saving an XML or SGML file so that it is easily readable in Plain Text view by adding whitespace, for example, by indenting lists to reflect a nested structure.

PRE-like elements

Elements that are formatted to look like the HTML PRE element; that is, with all whitespace preserved exactly as it was entered.

processing instruction

An instruction that is not interpreted as part of the documentâ&#x20AC;&#x2122;s content, but rather interpreted by an application that is processing the file.

public identifier

A system-independent string that is used to represent a DTD or entity file. Part of an external identifier.

RCDATA

Replaceable character data. SGML files can have RCDATA elements and marked sections, in which any element start- or end-tags that occur are interpreted as text, but any entity references are interpreted in the normal way.

referenced content

Content that is stored outside of the current element, either within the same file or in another file.

required attribute

An attribute that must be present in order for the document to be valid.

required element

An element that must be present in order for the document to be valid.

remote file

A file on an http or Web server.

rules checking

An XMetaL feature that ensures that you do not break the required structure as you edit your document; it does this by allowing you to insert only valid elements. Rules checking is less stringent than validation in that it checks that no errors have been made, but does not check that the markup is complete.

rules file

An XMetaL-specific alternative to a DTD. All of the files comprising a DTD are compiled into a single binary rules file. Rules files can be issued to XMetaL users who are not authorized to modify the DTD.

schema

An XML standard for defining the structure, content, and semantics of an XML document.

SDATA entity

A type of text entity whose content is specific to a particular processing application or platform. These entities are often used to represent platform-specific characters, and codes for formatting systems (such as troff or TEX). SDATA entities are permitted only in SGML files.

selector

In a cascading style sheet, a selector is an expression, representing one or more elements, that a style property can be associated with. A selector can represent an


XMetaL | Glossary | 193

element, several elements, an element with a specific ancestor, an element in a particular class, etc. semantic tables

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.

SGML

Structured General Markup Language. A standard for describing the structure of a document using markup. SGML is described by the ISO 8879 standard 1986). HTML and XML are applications of SGML.

SGML declaration

An SGML declaration is a file associated with a DTD that contains information about the character set, markup delimiters, quantity settings, and special markup features that are available in documents that use that DTD.

SQDIR

The variable that is used to represent the folder in which XMetaL is installed.

standalone document An XML document that an application can parse without referring to an external DTD. A standalone document may still require a DTD in some situations, for example, if it is being edited. system identifier

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 documents, system identifiers are required in external identifiers, and are interpreted as URLs.

tags

An element in an XML or SGML file begins with a start-tag (for example, <PRE>) and ends with an end tag (for example, </PRE>).

TBR

Toolbar file. Toolbar and menu customizations are saved in TBR files. When XMetaL Author loads a TBR file, it looks for the file in the userâ&#x20AC;&#x2122;s personal settings folder first. If it does not find the file, it then looks for the file in the folder specified by the tbr_path variable in the XMetaL configuration file. By default, this variable is set to the rules_path value. If it does not find the TBR file in either of these places, it looks for it in the folder that contains the DTD or schema, if this is a folder other than the Rules folder.

text entity

A type of general entity that stands for one or more text characters.

transformation type

A set of Java and XSL processing instructions as supplied in a script file to the DITA Open Toolkit.

Unicode

A standard for electronically encoding the characters of many of the scripts used to write the worldâ&#x20AC;&#x2122;s languages, as well as special symbols such as mathematical symbols. Unicode is the character encoding specified by XML. For more information, see www.unicode.org.

URL

Uniform Resource Locator. A URL is the address of a file, written in a format that can be interpreted by a Web server.

valid document

An XML or SGML document is valid if it is well-formed and if it conforms to the rules in the DTD or XML schema.

VBScript

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 the COM interface .

W3C

World Wide Web Consortium, an industry association for the development of World Wide Web technologies. For more information, see www.w3.org.

WebDAV

World Wide Web Distributed Authoring and Versioning, the Internet Engineering Task Force standard for collaborative authoring on the Web. WebDAV is a set of extensions to the Hypertext Transfer Protocol (HTTP) and Secure Hypertext Transfer Protocol (HTTPS) that facilitates collaborative editing and file management between users located remotely from each other on the Internet.


194 | XMetaL | Glossary

well-formed document

An XML document that is structurally correct according to the XML standard. There are several aspects to well-formedness, the most important of which are: the document must have only one top-level element, and all elements must be properly nested.

whitespace

One or more space, tab, carriage return, or line feed characters, in any combination.

World Wide Web

This is a generic term for the collection of Web servers and browsers. Usually abbreviated as WWW, or simply called â&#x20AC;&#x2DC;the Webâ&#x20AC;&#x2122;.

XAC

XMetaL Application Customization file. A compiled, deployable customization file. It contains all the files created or copied during the build process, and is recognized by XMetaL Author and XMetaL XMAX as a customization.

XFT

XMetaL Forms Toolkit. A set of form creation and form layout tools that developers can use to design and implement embedded forms and modal dialog boxes.

XML

Extensible Markup Language. An easy-to-implement subset of SGML, originally designed for displaying content over the Internet. XML is an initiative of the W3C. For more information, see www.w3.org/XML.

XML declaration

A processing instruction that appears at the start of an XML document. This processing instruction indicates the XML version being used, and may specify the character encoding and whether the document needs an external DTD.

XSLT

Extensible Stylesheet Language: Transformations. A language for describing how to transform an XML document into another XML document.


XMetaL | Index | 195

Index .dita extension, specifying in deliverable type 153 .rls/.rlx/.rld files 30 .tbr files 108 .xft 159

A abbreviations lists, creating 141 abstracts, creating 141 accelerator keys 113 accepting tracked changes 84 Access databases 101 access keys 113 Acrobat Distiller 148 adapter configuration file 163 adding rows and columns 78 alternate sorting, for index terms 128 alternative text element versus alt attribute 71 in element 70, 71 ancestor elements 17, 46, 49 Ant parameters 150 Antenna House XSL Formatter 148 Apache FOP 148 appendixes, creating 141 applying conditions 155 args parameter 145 aspect ratio 70, 71 asset templates 99 assets 98, 99, 100 adding objects to an asset folder 100 asset templates 99 Assets tab 98 creating a new folder 99 creating your own 99 customizable asset templates 98, 99 inserting in a document 99 My Assets folder 99 Assets tab 98 attach content reference 135 attribute declarations (Schema support) 30 attribute group definition (Schema support) 30 Attribute Inspector 19, 50 in Plain Text view 19 tabs 50 attributes 20, 46, 49, 50, 62 displaying in structure view 20 editing 50 finding 62 removing 62 searching for 62 special characters 49 AttributeUses (Schema support) 30

B back matter, creating 141 bibliographies, creating 141 Blank XML Document template 51, 107 blue diamond (to denote empty elements) 46 BMP files 72 bold text in DITA documents 124 book lists, creating 141 bookmap metadata 140 bookmaps 140 browsers associating with buttons 27 removing from Preview toolbar 27 built-in entities 38

C CALS tables 73, 75, 76, 77 cell properties 77 inserting 76 properties 75 Proportional column widths 76 caption, HTML table 74, 75 cascading style sheets structure view 20 case, names 29 CDATA sections 38 cells, table 73 change display font size 159 change list 17 changes accepting tracked 84 rejecting tracked 84 tracking 83 changing options 110 chapters, creating 141 characters converting to entities 45 non-ASCII 45 special 45 checking markup 31 checking spelling 85, 92 CHM output customizing 165 chunking 146, 147 setting 147 Close 54 Close All 55 closing multiple documents 55 cmd_always_open_log parameter 143 Collapse command 18


196 | XMetaL | Index

collapsing/expanding tags 18 colophons, creating 141 column properties 77 comment status XMetaL Reviewer 164 comments displaying 37 filtering 164 inserting 37 removing 164 comments, text vs. draft-comment element 37 complex type definitions (Schema support) 30 components 133, 134 concept topics 120 condition configuration file 154 conditional text 128, 154, 155 show or hide 155 conditions 154, 155, 156 applying 155 attributes 156 changing appearance of 155 configuring 156 creating 154, 156 defining 154, 156 generating output for 154 multiple 154, 155 otherprops attribute 156 styling 155 configuration 106 configure XMetaL for a specialization 157 conref attribute 131, 134, 135 detach 135 content authoring 119, 123 DITA sample files 123 DITA Language Reference 123 editing 119, 123 Help on current element 123 re-using 131 updating 132 content re-use 121 content reference attach 135 detach 135 insert 134 previewing 134, 135 content references displaying 132 editing 132 generalizing element names with 133 removing 132 updating 132 validating 132 content repository 161 context area 17, 46, 49 contracting cells 80 copycss parameter 166 copying text 58

create abbreviations list 141 abstract 141 appendix 141 back matter 141 bibliography 141 booklist 141 chapter 141 colophon 141 dedication 141 DITA bookmap 140 DITA map 136 draft introduction 141 figures list 141 front matter 141 glossary 141 index 141 new topic 123 notice 141 part 141 preface 141 reusable component 133 special topic 141 table of contents 141 tables list 141 topic 137 trademark list 141 create a template for a specialization 158 cross-references 125, 126 insert 126 CSS files custom 166 current element 17, 46, 49 custom formatting for a specialization 159 customizable asset templates 98 customizing 106 customizing XMetaL Author 107, 108, 109, 110 menu commands 109 menus 109 submenus 109 templates 107 toolbar buttons 108 toolbars 108 Cut 59

D data file (thesaurus) 90 database import 101, 102, 103, 104, 105 choosing databases 101 choosing fields 102 field properties 103 filtering records 103 formatting table and element output 103 table joins 104 updating tables 105 databases 101 declaration subset 34 dedications, creating 141 definition lists 68


XMetaL | Index | 197

deleting rows and columns 79 deliverable types 143, 144, 147, 148, 167 creating 147 editing 148 parameters 167 XMetaL Enhanced 144 demote topic (DITA) 127 Desktop tab 98 detach content reference 135 diamond (to denote empty elements) 46 DITA 14, 15, 73, 119, 123, 157, 158, 159 defined 119 references 15 sample map file 14 sections 123 specializations 157, 158, 159 tables 73 DITA Architectural Specification 122 DITA bookmaps 138, 139, 140, 141 create 140 editing 138, 139, 140 generated components 140 insert abbreviations list 141 insert abstract 141 insert appendix 141 insert back matter 141 insert bibliography 141 insert booklist 141 insert chapter 141 insert colophon 141 insert component 140 insert dedication 141 insert draft introduction 141 insert figures list 141 insert front matter 141 insert glossary 141 insert index 141 insert notice 141 insert part 141 insert preface 141 insert special topic 141 insert table of contents 141 insert tables list 141 insert trademark list 141 XML view 139 DITA Configuration Save Copy as Template macro 158 DITA Language Reference 122 DITA maps 127, 136, 137, 138, 139, 148 element 136 element versus title attribute 138 create 136 editing 136, 138, 139 fixing validity problems 136 generate output for 148 insert another map 138 insert Eclipse navigation reference 138 insert topic 137 insert topic group 137 insert topic heading 138 map editor 136, 138 reference to non-DITA files 137

DITA maps (continued) refreshing references 127 relationship tables 138 XML view 136, 139 DITA Open Toolkit troubleshooting 153 version 145 DITA Open Toolkit User Guide 122 DITA options 111 DITA_OT_NEW parameter 145 DITAVAL files 155 DocBook 148 docked panes 20 DOCTYPE 19, 33, 34, 41 internal subset 34 suppressing 19 document metadata 127 document publishing 143 document type declaration 33 document type name 33 document views 17 documents moving between 55 saving 53 structure 31 domains hiding and showing 111 download referenced components 161 draft introductions, creating 141 dragging-and-dropping text 58 DSDK_PARAM_ditaext parameter 153 DTD-less documents 55 DTDs 30, 34, 51, 106 configuration of XMetaL 106 internal 34

E Eclipse Content 148 Eclipse Help 148 Eclipse navigation reference 138 edit deliverable type 148 DITA bookmap 140 DITA bookmaps 138, 139 DITA map 136 DITA maps 138, 139 element properties 128 image properties 128 index markers 128 reusable component 128 table properties 128 topic metadata 128 editing accepting tracked changes 84 rejecting tracked changes 84 source 19, 32 text 58 text entities 44 tracking changes 83


198 | XMetaL | Index

element inline 124 insert 124 element declarations (Schema support) 30 element properties 128 elements ancestor 46, 49 attributes 50 current 46, 49 empty 46, 49 finding 62, 63 inserting 46, 124 replacing 62, 63 selecting 58 EMF files 72 empty elements 29, 46, 49 empty.gif file 46, 49 enlarging the document pane 21 entities 38, 41, 42, 43, 44, 45, 53, 71 built-in 38 changing 44 converting to characters 45 creating 43 deleting declarations 44 external 43 figure 42 general 41 inserting 44 naming conventions 41 opening external 43 opening external entities 53 parameter 43 representing images 71 text 42 entity content types 42 entity references 29, 44, 62, 63, 64 finding 63, 64 replacing 63, 64 replacing text 62 replacing with text 64 EPS files 72 error checking 85, 92 Euro symbol 45 Excel spreadsheets importing 101 pasting as tables 82 Expand 18 extended publishing options specifying parameters 150 external entities 43 external identifiers 29

F figure with title 71 figures 71 aspect ratio 71 figures lists, creating 141 file and folder naming rules 153 filename prefix 112 filenames 112

files creating from a DTD/rules file 51 creating from a template 51 creating new 51 DTDs 30 opening 51 printing 57 rules files 30 saving 53 Find and Replace 61 finding attribute values 62 elements 62, 63 entity references 63, 64 text 61 text in an element 62 using pattern matching 64 finding comments 164 finding information 15 floating panes 20 font size, changing 159 footers 166 form 159 Formatting toolbar 24 front matter, creating 141 full screen mode 21

G general entities 41 generalizing element names 133 generate IDs 159 generate output 146, 148, 153 chunking 146 troubleshooting 153 getting started 119 GIF files 72 glossaries creating 141, 142 sorting 144 glossary terms sorting 142, 146 graphic entities 42 graphics 72

H headers 166 headings within topics 123 height (images) 71 Help compilers 147 Help viewers 147 here 118 HTML Help 143, 148 HTML Help Workshop 147 HTML tables 73, 76, 77 cell properties 77 column properties 77 inserting 76 properties 76 row properties 77


XMetaL | Index | 199

I ICO files 72 identifier external 33 public 33 system 33 IDs 111 changing format 111 image properties 128 images 70, 71, 72, 110 alternative text 71 aspect ratio 70 BMP files 72 EMF files 72 EPS files 72 formats supported 72 GIF files 72 height 71 hiding 110 ICO files 72 IMG element 71 inline 110 inserting 70 JPG files 72 PCX files 72 PNG files 72 represented by entities 71 showing 110 source file 71 SVG files 72 TGA files 72 TIF files 72 vertical alignment 71 width 71 WMF files 72 IMEs 35 importing databases 101 Excel spreadsheets 101 index markers 128, 129 creating 128 page ranges 128 See and See also entries 128 sorting 128 sub-entries 128 indexes, creating 128, 141 inline element 124 inline elements 124 inline images 110 input method editors 35 insert abbreviations list into a DITA bookmap 141 abstract into a DITA bookmap 141 appendix into a DITA bookmap 141 back matter into a DITA bookmap 141 bibliography into a DITA bookmap 141 booklist into a DITA bookmap 141 chapter into a DITA bookmap 141 colophon into a DITA bookmap 141 component into a DITA bookmap 140 content reference 134

insert (continued) cross-reference 126 dedication into a DITA bookmap 141 definition list 68 draft introduction into a DITA bookmap 141 element with content reference 134 elements 124 figure with title 71 figures list into a DITA bookmap 141 front matter into a DITA bookmap 141 glossary into a DITA bookmap 141 headings within topics 123 image 70 index into a DITA bookmap 141 index markers 129 inline elements 124 link 126 list 67 list item 67 list of steps 125 metadata 127, 140 multimedia object 125 notices into a DITA bookmap 141 object 125 part into a DITA bookmap 141 preface into a DITA bookmap 141 reference to a non-DITA file into a DITA map 137 related link 126 relationship table 138 reusable component 134 special topic into a DITA bookmap 141 step component 125 subtopic 123 table of contents into a DITA bookmap 141 tables list into a DITA bookmap 141 task 125 topic group into a DITA map 137 topic into a DITA map 137 trademark list into a DITA bookmap 141 URL into a DITA map 137 inserting CALS tables 76 comments 37 elements 46 HTML tables 76 inserting elements 46 integrating revisions XMetaL Reviewer 164 interface document views 17 introduction 17 Normal view 17 Page Preview 19 pane buttons 20 panes 20 Plain Text view 19 tag tips 18 Tags On view 18 toolbars 23 workbook mode 22 workspaces 22 internal DTD 34


200 | XMetaL | Index

internal subset 34, 41 ISO 8859-1 character set 35, 45 ISO Latin 1 45 ISO numeric characters 45 italic text in DITA documents 124

J Java parameters 150 JavaHelp 148 JPG files 72

K keyboard shortcuts 113

L language, specifying 146 languages 86, 88, 91 Latin 1 character set 45 limitations wildcards 30 link element 125, 126 links 121, 125, 126 relationship tables 121 list items 67 list of steps 125 lists changing type 68 converting block elements to 68 converting paragraphs to 68 inserting 67 inserting a list in a list 67 local and active entity set 44 local content 131 log file 143

M macros 78, 94, 96, 97, 109 changing shortcut key 96 default macro file 94 defined 94 deleting 97 inserting a tab in a table 78 loading 94 locations 94 macro files 94 restrictions 94 running 94 Macros 94 Macros toolbar 26 main word lists 86 adding 86 removing 86 map references 138 maps 121, 136 relationship tables 121 See DITA maps 136

Marked Section (Insert menu) 40 marked section parameters 38, 39 result parameters 39 marked sections 38, 43 parameter entities 43 marking revisions 83 markup 17, 19, 31, 110 display options 110 repairing 31 source editing 19 validating 31 menu commands, custom 109 menus, custom 109 merging cells 80 metadata 127, 140 mini-template 132 minimization 29 mnemonic 113 model group definitions (Schema support) 30 model groups (Schema support) 30 monospaced text in DITA documents 124 moving between documents 55 moving rows and columns 79 multimedia object 125 multiple documents 22 multiple panes 20 multiple-user settings 106, 108 My Assets folder 99

N names 29 naming rules, for files and folders 153 New 51 new document 51 non-ASCII characters 45 Normal table 73 Normal view 17 notation declarations (Schema support) 30 notes in DITA documents 124 notices, creating 141

O OASIS (CALS) tables 73 omitted tags 29 Open 51 open a DITA bookmap component 141 open referenced file 141 opening documents 51 external entities 53 files in WebDAV-enabled folders 53 remote files 51 templates 51 options 110, 111 auto-saving 110 DITA 111 File 110 font 110


XMetaL | Index | 201

options (continued) General 110 show/hide inline images 110 syntax coloring 110 tab 110 tooltips 110 View 110 word wrap 110 otherprops attribute 154 outline view 20 output formats 148, 152 creating 152 distributing 152 modifying 152 output log 143, 153 output options for a deliverable type 145 global 145 local 145 output parameters 150 overriding formatting for base DITA elements 159

P Page Preview 19 page ranges, for index terms 128 panes Attribute Inspector 20, 50 behavior 20 buttons 20 docked 20 Element List 20, 46 floating 20 options 20 Resource Manager 20, 98 rules for docking and floating 20 paragraphs in DITA documents 124 parameter entities 43 parameters 150 Particles (Schema support) 30 parts, creating 141 Paste 59 pasting 58 pattern matching 64, 65 summary 65 PCX files 72 PDF 143, 148 PDF output customizing 173 generate IDs for 159 localizing 184 special requirements in specializations 159 personal settings 95, 106, 108 phrases in DITA documents 124 placeholder content 131 Plain Text view 19 available commands 19 PNG files 72 prefaces, creating 141

prefix filename 112 preformatted text in DITA documents 124 preview options 143 Preview toolbar 26 print formatters 148 printing 57 processing instructions 29 promote topic (DITA) 127 prompt text 46, 132 properties editing 128, 138 Properties table 73 public identifier 33 PUBLIC keyword 33 publishing 143, 145, 148 generate output 148 output options 145 preview options 143 publishing configuration files 150

Q quotations in DITA documents 124 quotes in DITA documents 124

R raw code editing 19 re-using content 131 read-only elements 46, 49 reference topics 120 referenced content 131 references refresh 127 refresh all references 127 rejecting tracked changes 84 related links 125, 126 insert 126 relationship tables 121, 138 remote files 51 removing comments 164 RenderX XEP 148 repair table structure 73 replacing elements 62, 63 entity references 63, 64 entity references with text 64 text 61, 62 text with entity reference 62 using pattern matching 64 repository adapter 161 repository configuration file 163 repository file creating 162 creating new map 162 repository integration layer 161 repository map file opening 161


202 | XMetaL | Index

Repository toolbar 162 repository topic file opening 161 Resource Manager Assets tab 98 defined 98 Desktop tab 98 editing images 98 inserting images 98 inserting objects 98 restricting spell checking 85 result parameters 39 reusable components create 133 displaying 132 edit 128 editing 132 inserting 134 removing 132 updating 132 validating 132 Reviewing toolbar 28 revision marking 83 revision status XMetaL Reviewer 164 revisions accepting marked 84 integrating in XMetaL Reviewer 164 rejecting marked 84 tracking 83 Rich Text Format 148 row properties 77 RTF 148 rules checking 31, 32 rules files 30, 51 Rules folder 30 running macros 94

S sample files 14 Save 54 Save All 54 Save As 54 Save Copy as Template macro 158 saving documents 53 multiple documents 54 options 110 validating before 53 schemas configuration of XMetaL 106 Schemas limitations 30 rixml support 30 support for 30 screen tips 110 SDATA entities 29 Search options 61 search patterns 64, 65 summary 65

searching 61, 62, 63, 64 for attribute values 62 for elements 62, 63 for entity references 63, 64 for text 61 using pattern matching 64 within an element 62 sections CDATA 38 in DITA topics 123 marked, in SGML 38 See and See also entries, for index terms 128 selection methods table cells 77 settings multiple users 106, 108 personal 95, 106, 108 SGML 29, 38, 46, 49, 50 attributes 50 differences from XML 29 empty elements 46, 49 marked sections 38 short description 120 shortcut keys 113, 114, 115, 116, 117, 118 choosing menu commands 117 editing commands 113 formatting lists 115 making and extending selections 116, 117 moving around in a document 115 moving around in tables 116 moving between panes and dialog boxes 117 navigating in a dialog box 118 switching views 114 text and markup operations 114 working with files 113 showing inline images 110 showing or hiding conditional text 155 Simple table 73 simple type definitions (Schema support) 30 Smart Insert 124 sorting, for glossary terms 144, 146 sorting, for index terms 128 source editing 19 special characters 45 Special Characters toolbar 28 special topics, creating 141 specialization attributes 111 specializations 157 specialized menus and toolbars 157 specify XSL stylesheet 145 spell checker 85, 86, 87, 88, 92 languages 86 options 86, 87, 88, 92 word lists 86, 87, 88 spell checking restricting 85 Split Cell into Columns 80 splitting cells 80 elements 47 splitting elements 47


XMetaL | Index | 203

SQL 101 Standard toolbar 23 status of comments XMetaL Reviewer 164 Step choices table 73 step component 125 structure view 20 style conditions 155 sub-entries, index terms 128 submenus, custom 109 subscript in DITA documents 124 subtopics 123 superscript in DITA documents 124 support for Schemas 30 SVG files 72 symbol characters 45 Symbols toolbar 28 system identifier 33 SYSTEM keyword 33

T Table Advanced toolbar 26 table cells contracting 80 entering tab character 78 height (HTML) 79 merging 80 properties 77 properties (CALS) 77 properties (HTML) 77 selecting 77 spanning 80 splitting 80 width 79 table properties 128 Table Properties 76 Table toolbar 25 tables 73, 74, 75, 76, 77, 78, 79, 80, 82, 101, 103 adding rows and columns 78 CALS Proportional column widths 76 CALS properties 75 caption (HTML) 74, 75 cell properties (CALS) 77 cell properties (HTML) 77 cells 73 change body row to header row 77 change header row to body row 77 column properties (CALS) 77 column properties (HTML) 77 column/cell width 79 contracting cells 80 deleting rows and columns 79 Editing attributes 74, 75 from database 101 header rows 77 HTML properties 74 inserting (CALS) 76 inserting (HTML) 76

tables (continued) moving rows and columns 79 navigating in 78 pasting from other applications 82 properties (HTML) 76 repairing 73 row properties (CALS) 77 row properties (HTML) 77 row/cell height (HTML) 79 splitting cells 80 width (HTML) 76 working with HTML tables 73 XML model 103 tables lists, creating 141 tables of contents, creating 141 tag icons 18 collapsing/expanding 18 tag tips 18, 46, 49 tag-valid markup 31 Tags On view 18 task 125 task topics 120 teletype text in DITA documents 124 templates 51, 107 creating 107 text finding 61 finding in an element 62 replacing 61, 62 replacing entity references 64 replacing with entity 62 text entities 42, 44 editing 44 Text Processor for Typesetters 148 TGA files 72 thesaurus 88, 89, 90, 92 data file 90 languages 88 options 89, 90, 92 TIF files 72 tips in DITA documents 124 toolbars 23, 24, 25, 26, 27, 28, 108, 109, 162 built-in 23 custom 108 custom buttons 108 Formatting 24 Macros 26 Preview 26 Repository 162 Reviewing 28 Special Characters 28 Standard 23 Symbols 28 Table 25 Table Advanced 26 Views 27 tooltips 110 topic heading in DITA map 138 topic headings 138 topic metadata 127, 128


204 | XMetaL | Index

topic references 138 topics 120 topics, creating 123, 137 topics, promoting or demoting in DITA 127 tracking changes 83 trademark lists, creating 141 transformation type 148 transtype 148 TROFF 148 troubleshooting 153

U underlined text in DITA documents 124 Unicode 35, 36 updating content when opening files 111 updating references when opening files 111 URLs 137 US-ASCII encoding 35 user word lists 86, 87, 88 adding 87 default 87 entries 87, 88 User's Guide 15 UTF-8, UTF-16 encodings 35

V Validate document 32 Validate Document 19, 31 in Plain Text view 19 Validate selection 32 validation 19, 31 document 31 selection 31 XML 31 vertical alignment 71 View SQL tab 101 viewing properties 138 Views toolbar 27

W warnings in DITA documents 124 Web links 126, 138 Webdav 51 WebDAV 53 file caching 53

WebDAV (continued) opening files 53 well-formed editing 55, 56 adding new attributes 56 adding new elements 56 well-formed markup 29, 31 width (images) 71 wildcards Schema 30 windows 20 WMF files 72 word lists 86, 87, 88 main 86 user 86, 87, 88 workbook mode 22 workspaces 22 writing tools 85, 86, 87, 88, 89, 90, 91, 92 languages 86, 88, 91 spell checker 85, 86, 87, 88, 92 thesaurus 88, 89, 90, 92 WYSIWYG editing 17

X XHTML 148 XHTML output customizing 165 XMetaL Connector 161 XMetaL Evaluation Guide 122 XMetaL form 159 XMetaL Reviewer 164 comment status 164 finding comments 164 integrating revisions 164 removing comments 164 xml lang attribute 146 XML 15, 17, 19, 29, 31, 41, 46, 49, 50 attributes 50 differences from SGML 29 editing 29 empty elements 46, 49 entities 41 references 15 source editing 19 specification 15 version 29 well-formed markup 31 XML declaration 35 XML table model 103 xref element 125, 126


XMetaL Author 5.1 Enterprise Edition User&apos;s Guide