XMetaL Author Enterprise Edition is the leading authoring application for organizations using any XML document type, including the most complete support for the Darwin Information Typing Architecture, or DITA. Enterprise Edition also helps you maximize content reuse through tight integration with content repositories, address advanced publishing requirements with an extensible publishing framework, and improve collaboration with reviewers by being able to merge XMetaL Reviewer comments directly into your documents.
With Version 5.1, XMetaL Author extends the functionality and ease-of-use that has already made it more intuitive than Microsoft Word plug-ins or any other structured authoring solution on the market, while still providing the power and flexibility of professional desktop publishing tools.
This document contains information on:
This release includes support for DITA 1.1 and bookmaps. You can create and edit bookmaps in the Map XML View or browse bookmaps in the Map Editor. Bookmaps define book-style print deliverables, identifying all parts of a book including front matter, back matter, parts, chapters, glossaries, and various types of lists and figures. This release includes the following enhanced bookmap support features:
By default, XMetaL Author hides the new indexing and xNAL domains. You can change this setting through the DITA Options dialog.
A number of markup changes have occurred since DITA 1.0; see the table below for a summary.
Note: Validation errors may occur when you try to open documents created with a previous DITA DTD. You can convert your existing documents created with DITA 1.0 using the Ditacleaner utility.
DITA 1.1 includes specialization support for new global attributes, such as conditional processing attributes.
| File | Markup affected | Change |
|---|---|---|
| concept.mod | <concept> element | Added <abstract> element |
| ditabase.dtd | info-types parameter entity | Added <glossentry> element |
| map.mod | <map> element | Added <title> element |
| map.mod | <map> element | Removed <keyword> element |
| indexingdomain.mod | New indexing elements | |
| xnaldomain.mod | New address elements | |
| xmlns:ditaarch attribute | Removed #FIXED value | |
| DITAArchVersion attribute | Removed #FIXED value | |
| global-atts parameter entity | Removed xmlns attribute | |
| <ditacomponent> element | Value of DITAArchVersion attribute is now 1.1 |
DITA 1.1 is the default DTD. If you do not wish to use DITA 1.1, you can revert to DITA 1.0 by following these steps:
Note: To revert to the default shipped DITA DTD, copy the files in C:\Program Files\XMetaL 5\Author\DITA\DITA_1.1_DTD and paste them in C:\Program files\XMetaL 5\Author\DITA\DITA_OT_DTD, overwriting the existing files in that folder.
Previous versions of XMetaL Author created files that conform to DITA 1.0. These files include some attributes that are not allowed in DITA 1.1 and they will cause validation errors if you attempt to edit them or generate output using DITA 1.1. For this reason, we have supplied the ditacleaner utility.
The ditacleaner utility is a command-line tool that you can use to clean files of attributes that are not allowed in DITA 1.1. The tool is installed at C:\Program Files\Common Files\XMetaL Shared\ditacleaner. Configuration settings are stored in config.xml. By default (that is, without editing the configuration file), the tool removes the xmlns, ditaarch:DITAArchVersion, domains, class, and xmlns:ditaarch attributes with empty values from files with .xml, .dita, and .ditamap extensions. (By default, previous versions of XMetaL always created these attributes with empty values, for example, ‘xmlns=""’.)
If you need to change the default configuration settings, for example, if you specified a value for any of the abovementioned attributes, you can edit the configuration file in a text editor. Attributes to be removed are specified in the AttrName property. You can specify a string or regular expression in the attrValuePattern property. If you specify a value, only attributes that match the value are removed.
You are advised to convert all existing DITA 1.0 documents to DITA 1.1 at one time to avoid version and compatibility issues.
We recommend backing up your existing documents before working with this tool.
To use the tool, do the following:
cd Program Files\Common Files\XMetaL Shared\ditacleaner
ditacleaner -c config_file_path file_path|folder_path
| -c | Allows you to specify an alternate configuration file. This argument is optional; by default config.xml is used. |
| file_path | Specify a file to clean using the AttrName and attrValuePattern properties contained in the configuration file. |
| folder_path | Specify a folder containing DITA files. File types to clean are read in from the configuration file. Files contained in sub-folders are also cleaned. |
You can specify one or more files and folders on the command line. Here is an example:
ditacleaner c:/temp/file1.xml c:/temp2/files.xml d:/legacy
The embedded DITA Open Toolkit has been upgraded to Version 1.4, which includes support for DITA 1.1 and provides more publishing options. The embedded toolkit also includes version 1.4.1 of the FO plug-in from Idiom Technologies.
This release has been tested with the DITA Open Toolkit versions 1.3.1, and 1.4.
This version of XMetaL Author includes RenderX® XEP 4.9 print formatter for enhanced PDF output. XEP is used in XMetaL Enhanced deliverable types.
XMetaL now supports the DITA 1.1 indexing domain. The Insert Index Marker dialog includes support for the following:
All DITA dialogs have a consistent look and feel and feature improved keyboard support.
You can now use specialized attributes in the condition configuration file ../XMetaL/Author/Conditional Text/configs/ct_config.xml. These conditions appear in dialogs that let you specify conditions, such as the Generate Output dialog. Requires specialization to define new attributes.
You can now add topic groups to maps and view them in the Map Editor.
A <linktext> element is automatically added to a related link when the scope attribute has the value of ‘peer’.
MathML is supported using the new <foreign> element in DITA 1.1. A third-party control (e.g., MathFlow from Design Science) is required to view and edit MathML.
A macro is provided that allows an administrative user to save a DITA document instance as a template. The macro strips out element IDs and performs other functions required in a template.
Images can be scaled in the editor to an absolute size or to a percentage. You can also set width and height for an <object> element. You can also specify alternative text.
The online Help now includes the following:
PDF output can be configured by specifying parameter values. Parameters include: header/footer content and layout, page margins, fonts, and table styles.
Glossary entries are merged for all output formats. In PDF output, glossary entries are sorted according to the language specified.
The new XMetaL Enhanced deliverable types give you print-quality deliverables out of the box. They are configurable by parameters and include support for glossaries and sorting by language. EPS graphics are also supported. They are enabled by a new transtype, PDF3, that is an enhancement to the Toolkit PDF2 type. For more information, see PDF enhancements.
Customers can contact JustSystems Technical Support for assistance with configuring the DITA Open Toolkit. A document describing support policies for the Toolkit will be available from www.xmetal.com.
The XMetaL Author User Guide and online Help now contain detailed information on configuring your PDF, HTML, and CHM output.
You can publish EPS graphics using the ‘XMetaL Enhanced PDF via Acrobat Distiller’ deliverable type. EPS Graphics display in vector format in PDF output. Requires installation of Adobe Distiller.
Deliverable types have been renamed and normalized.
The ‘Single HTML file advanced’ deliverable type has been renamed to ‘Single HTML file (example)’ and disabled by default.
This release includes a new model for handling referenced content as implemented by the DITA conref attribute. The model is based on a general purpose transclusion mechanism in the XMetaL binary, and is scriptable so that other transclusion models (e.g. XInclude) will potentially be able to make use of it.It fully supports the new DITA 1.1 rules for merging attributes on elements that have a conref attribute.
The new implementation makes it easier for authors to edit or remove conref attributes. It does not persist transclusions in the referencing document, ensuring that there are no issues with stale content, redundant search hits, or violating CMS unique object rules.
Users can select either WYSIWYG or Tags On preview of targets in Insert Content Reference dialogs. This makes it easier for users to select the right target.
You can easily attach (or detach) a content reference to (from) any element.
You can show or hide any content reference. When hidden, you see the the placeholder element that contains the conref attribute and local content, if any. The placeholder is editable and is also distinctly styled to indicate that it contains a content reference. When the content reference is shown, you see a read-only view of the referenced content. Show/hide can be performed on individual content references.
You can refresh content references on an individual or global (per-document) basis.
A progress dialog indicates the progress of the Refresh All References process (previously known as Update References). The process can be cancelled if desired.
The Insert Element with Content Reference and the Insert Reusable Component commands insert a generalized element that is valid in the current context when a reference is made to a specialized element that is not in the current content model. For example, if a user creates a content reference to a <steps> element (in a Task topic) from a Reference topic an ordered list (<ol>) element is inserted. This is because <ol> is the parent class of steps, and it is valid within a Reference topic.
Users can still see the original (specialized) element names 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.
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, that is, that the target still exists (has not been moved, deleted, or renamed), and that it is valid within the content model of the document type.
| Error message | Description |
|---|---|
| Target file not found | The target file must exist |
| Target ID not found | The target ID in the target file must exist |
| Target document invalid | The target document must be valid XML |
| Circular link | The target must be a different node than the source node |
| Incompatible source and target elements | 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 |
| Incompatible domains between source and target | The target domain set must be equal to or a subset of the source domain set |
| Target element not in a topic or map | The target element must be a descendent of a topic or a map |
The trial version is identical to the full version of the product. You can unlock the full version by supplying a license key.
The trial version includes a trial version of RenderX XEP. This version has all of the functionality of the full version except that a watermark appears on each page and every second page blank after page 11 is blank.
When refreshing references (for example, content references or cross-references), performance has been significantly improved.
The option to refresh references when opening topics and maps is now enabled by default. You can change these settings by clicking Tools > DITA Options and selecting the Update Content tab.
This version includes certified support for deploying XMetaL Author on Citrix servers, including access by Limited users.
This version includes an unattended installer for Citrix servers that can be used with the Citrix Package manager to deploy across a Citrix server farm.
| Feature | Description |
|---|---|
| Documents no longer automatically saved when output is generated | You are now asked if you want to save and warned that unsaved changes will not appear in output. |
| Improved simpletable authoring | Paragraph (<p>) elements are no longer added to simple tables by default. |
| Repair table structure | You can restore the structure of a simple table, properties table, or step choices table (for example, after backspacing and removing a cell) through the Repair Table Structure command. |
| Related link to Topic Properties no longer always sets scope to “local” | Scope is not updated automatically by the dialog if scope is set to another value. |
| .svg, .png, and .tif added to list of file types in browse for image dialog | XMetaL will now include SVG files by default in the file list. A third-party viewer is required to view SVG files in the authoring interface. |
| Ctrl+C now works in the Attribute Inspector | You can now use Ctrl+C/Ctrl+V to copy/paste values in the Attribute Inspector for DITA documents, in addition to being able to use the context menu for these functions. |
| SVG support | SVG graphics can now be referenced by the DITA <image> and <figure> elements. |
| Map Editor shows href in tooltip | The Map Editor now displays the href value for a topic reference instead of displaying the title (the title was already displayed in the map itself). |
| <alt> element for images, and <title> element for topic references | Insert dialogs now use the <alt> element for images, and the <title> element for topicrefs, rather than the respective attributes for those elements. This is consistent with DITA best practices. |
| ‘Friendly’ element names | The bottom of the Element List shows an English-friendly name for the element type that is selected in the pane. |
| Improved readability for element mini-templates | The default styling for mini-templates has been improved for readability by increasing the foreground/background contrast. |
| Improved styling for <lines> element | Whitespace in the <lines> element is now properly styled. |
| Spaces removed from new elements | By default, newly inserted elements do not include spaces. |
The XMetaL Enhanced deliverable types are designed to enable you to produce production-quality output out-of-the-box. These deliverable types include the following characteristics:
XMetaL uses the DITA Open Toolkit and a Java-based processor to generate output. When generating output, you may encounter errors caused by insufficient memory allocation or application wait time. To correct these errors, you can try some or all of the following:
You may encounter Java memory errors when generating output, particularly for large documents. You can correct this error by increasing the amount of memory allocated to your Java processor. By default, Java uses 128 Mb of memory, and if this process exceeds that amount, you will see the error ‘java.lang.OutOfMemoryError’ in the output log. You can increase the memory allocation to the Java processor by modifying the Xmx and Xms variables.
When generating output, you can monitor the amount of memory used by the Java process through the Task Manager. The Java process terminates with an out of memory error when the memory usage and virtual memory size become equal. (You can display these values through the View > Select Columns dialog in the Task Manager.) This allows you to determine the maximum amount of memory you require for a given output.
Note: The values of these variables may be higher or lower than those indicated in the procedure below. You are advised to increase the values until you are able to successfully generate output, or until the limit of available physical memory (RAM) is reached. For 32-bit versions of Windows (for example, Windows XP), the maximum memory that can be allocated to a process is 2 Gb (2048m).
<java classname="com.icl.saxon.StyleSheet" classpathref="project.class.path" fork="true">and add the following argument:
<jvmarg value="-Xmx1024m"/>Here is how the element should look:
<java classname="com.icl.saxon.StyleSheet" classpathref="project.class.path" fork="true">
<jvmarg value="-Xmx1024m"/>
...
<java>
<java classname="com.idiominc.ws.opentopic.fo.xep.Runner" resultproperty="errCode" failonerror="false" fork="true" maxmemory="256m">and change the maxmemory value to 1024. Then add the following argument:
<jvmarg value="-Xmx1024m"/>
ANT_OPTS = -Xms1024m -Xmx1024m
When generating output, XMetaL may display an error message before the Java process has finished. This situation is particularly relevant to versions of XMetaL before 5.0.10. You can correct this error by increasing the application wait time.
Note: This does not address the Java out-of-memory issue.
cmd_dita_ot_waiting_time = 3600
By default, all output formats, with the exception of PDF via RenderX, use the Xalan processor. However, you may be able to prevent out-of-memory errors by switching to the less memory intensive Saxon processor. The following procedure illustrates how to modify the HTML Help (CHM) deliverable type to use the Saxon processor.
Note: Switching to the Saxon processor may result in longer processing times.
cmd_always_open_log = yes
C:\Program Files\XMetaL 5\Author>set CLASSPATH=C:\PROGRA~1\COMMON~1\XMETAL~1\DITA_OT\lib\dost.jar;;C:\PROGRA~1\COMMON~1\XMETAL~1\saxon\saxon.jar;
Now when you generate output for HTML Help, you should see the following line in the log:
[echo] * xslt.parser = SAXON
The pretty-printing feature adds carriage return characters to lines that are longer than 80 characters. This may cause some image maps created with third-party applications and pasted into an XMetaL document not to work correctly in a browser. The workaround is to close all documents and run the ‘DITA_PrettyPrinting_OFF’ macro. Then open each document with an <imagemap> element and re-save the document.
When you add a new relationship table (<reltable>) to a map file in Normal view, the cursor may not behave as expected. Workaround: Switch to Tags On view and right-click the mouse and choose the Insert element option to add the relationship table.
When you are working in a large bookmap and attempt to switch to Page Preview, you may have unexpected results or a general protection fault.
When opening an invalid DITA document in well-formed mode or Plain Text view, XMetaL does not load the DITA customization. As a consequence, the DITA toolbars and menu items are not available. Workaround: Open the invalid document in plain-text view, fix the validation errors, and re-start XMetaL. If you have configured XMetaL to use the DITA 1.1 DTD, you must remove the ‘xmlns’ attribute from the DITA document and re-start XMetaL.
Setting CSS background-color or border for elements that contain large amounts of content may compromise the performance of the editor. Workaround: use a CSS override to set ‘border:none’ for the element. See the online Help for information on overriding base formatting.
The output from a topic or map that includes conditional text may contain conditions that you excluded through the Show/Hide Conditional Text dialog, or vice-versa. Workaround: Close XMetaL and remove the file C:\Documents and Settings\<userid>\Application Data\SoftQuad\XMetaL\5.1\ct_preferences.xml, then re-start XMetaL and try generating output again.
When the user drags and drops internal content from one location to another, if the drop point is correct the drop is successful. However, when the user performs a single Undo, the dropped text remains at the drop point even though the original text is returned back to the initial location. To return to the original state, perform two Undo operations.
The user can drag content from one location to another within a DITA topic. However, if the user drops the content in an invalid location, the action is accepted, but the content is never actually dropped and the original content is removed from the initial location.
When generating output, the presence of files in the output directory may cause the build to fail.
When editing a DITA map file in Plain Text view, adding a <topichead> element without a navtitle attribute, triggers a validation error. Although the DITA specification claims that this attribute is optional, it is, in fact, required by the DITA DTD.
There are several issues related to working with tables:
You may experience problems generating HTML and PDF if your DITA map contains topics with <conref> attributes that refer to reusable components that are saved outside of the directory in which your DITA map file is saved. It is recommended that you save your reusable components in the same directory on the same volume as your DITA map file or a directory below it.
When publishing footnotes to PDF using FOP, the footnote content is displayed within the document content and is not displayed within the bottom margin of the page. Contact XMetaL support to learn how to use a different stylesheet.
Although you can copy and paste (or cut and paste) paragraphs, headings, etc. from Microsoft Word and cell ranges from Microsoft Excel, some of the more complicated content structures cannot be pasted in their entirety into XMetaL documents. The workaround is to employ multiple copy-and-paste operations using a simpler and smaller set of content in each operation.
Windows 2000 Limited Users do not have full XMetaL DITA functionality. In particular, they cannot create any HTML/PDF output from DITA documents or DITA map files.
Web folders accessed in Windows XP must have ":80" appended to the server name.
For example, if your server is http://www.MySite.com/Folder, you must create the folder as: http://www.MySite.com:80/Folder.
WebDav is not supported for DITA documents.
Repeatedly deleting toolbars using scripting impairs the performance of XMetaL because of a memory leak.
When you create new topics from the Map Editor but do not open them, IDs are not assigned for the topics. The workaround is to open the topic and save it.
When you copy and paste a content reference, the local content, not the referenced content, is displayed. To display referenced content, click Reuse > Refresh and Show Referenced Content.
When a table row in a Normal table specifies referenced content, the referenced content is not displayed. Only local content is displayed.
Beginning with this release, the Assets tab is deprecated.
When you change a DITA element using the Insert Element list, if the element is empty or if it contains only other empty elements, attributes are lost.
Not all bookmap elements are supported by the DITA Open Toolkit. For example, when you generate output, the toolkit uses the title of the first topic-like element instead of the bookmap <mainbooktitle> element.
The following book lists are not provided out of the box:
These lists can be added by customizing the DITA Open Toolkit.
In order for referenced content to appear in output, the paths for all conref attributes must be relative to the file that contains them. To make sure that paths to referenced content are relative, do the following:
Before you generate output from a map on a Japanese operating system, do the following:
cmd_dita_ot_per_user_version = 0
When you generate output, you are asked if you want to upgrade to a newer version of the toolkit. Click OK.
Operations on bookmaps through the Map Editor are limited to viewing and opening references.
Generation of a copyright page, front cover, and back cover is not provided out of the box.
Cross-references that point to a <step> element appear with the text “list item” in output created using the PDF2 transtype. This transtype is based on the Idiom plug-in and provided by the DITA Open Toolkit. Because the PDF3 transtype is based on the PDF2 transtype, this issue also applies to the new XMetaL Enhanced deliverable types.
Cross-references that point to a <step> element appear with the step number in output created using the HTML and PDF1 transtypes.
The PDF2 and PDF3 transtypes include the following indexing limitations:
The default DITA Open Toolkit pdf2 (Idiom plug-in) processing fails when processing a bookmap that contains the <bookmeta> element.
The default DITA Open Toolkit pdf2 (Idiom plug-in) processing fails when processing a cross-reference that targets an element other than <topic>, <subtopic>, or <section>.
The default DITA Open Toolkit pdf2 (Idiom plug-in) processing fails when processing a content reference that cannot be resolved. In the same scenario, pdf3 (XMetaL Enhanced PDF) will generate with nothing where the conref should be, and it will report that the build was successful. Check the output log for errors.
The DITA Open Toolkit does not support the image scale property for Multiple HTML files and XMetaL Enhanced deliverable types. Images appear at 100% in output regardless of the value set for the scale property.
Processing fails when you try to generate output from a map that contains duplicate IDs using the Antenna House XSL Formatter print formatter.
If you create a map that contains a map reference and a topic reference and then demote the topic reference so that it is a child of the map reference, the topic reference does not appear in output. This issue applies to XMetaL Enhanced and HTML deliverable types.
This issue applies to limited users under Citrix. If you attempt to select languages from the XMetaL Author Spell Checking dialog, you will not be able to view a list of languages. In order to select a new language, users must have full Administrator access to their local operating systems.
This issue applies to limited users under Citrix. If you try to save a map in a protected folder (or location where you do not have permission to write), you will see an ‘Access denied’ warning. If you press OK to dismiss the warning, the close operation continues, but the map file is not saved.
There are various cases where an operation might not succeed because of permission issues. For example, you may be prevented from opening a generated PDF or CHM file that is saved to the local machine drive ($C). Another example is drag-and-drop. If you try to drop a file located on the client machine into XMetaL (running on the server), this will fail. However, drag-and-drop from the Desktop tab in the Resource Manager is supported.
For a list of telephone support offerings, online service options, and support downloads, visit http://na.justsystems.com/support.
To contact XMetaL support directly, e-mail us at support@xmetal.com, or telephone us at one of the numbers listed at http://na.justsystems.com/contact.