XMetaL® Author Enterprise 7.0 Install Readme

Installation Notes

These installation notes cover the following XMetaL installations:

Limited User vs. Local Admin accounts

All installations of XMetaL Author are now pre-configured to operate in an environment where end-users are assumed have 'Limited User' account privileges. Programs running under such user accounts are normally restricted from writing to Program Files and similar folders along with writing to Windows HKEY_LOCAL_MACHINE/HKEY_CLASSES_ROOT registry hives. XMetaL Author still has some features that require operating under a Local Admin user account in order to write to the Program Files folder. A prompt will appear warning the user of this restriction.

Features requiring Local Admin privileges

For all installations, features requiring Local Admin privileges are disabled. Here are the features that are disabled:
  • Tools > Select Specialized DITA DTD
  • DITA Configuration: Delete RLX Files macro
  • DITA Configuration: Turn OFF Pretty-Printing macro
  • DITA Configuration: Turn ON Pretty-Printing macro
  • DITA Configuration: Save Copy as Template macro
  • Drag-and-drop operations to and from Resource Manager Assets tab
  • Right-click menu does not show Assets tab operations
  • UI for assigning or reassigning shortcut key to an All Users macro
You can use these features by running XMetaL in Administrator mode. Follow these steps:
  1. Right-click on the XMetaL shortcut and choose 'Run as Administrator' (Vista) or 'Run as' (XP).
  2. Provide login account info of user with administrator privileges.
  3. Run operation requiring administrator privileges.
Note: The disabled features also require you to configure XMetaL Author for Local Admin privileges
Note: Regardless of being qualified as limited-user or local-administrators, users MUST chose 'Run as Administrator' on Windows Vista operating systems. Under Windows operating systems prior to Vista (and its UAC feature), users qualified as a local-administrator are not required doing the 'Run as' option.

Configuring XMetaL Author for Local Admin privileges

XMetaL Author is set up assuming users have only Limited User account privileges. If your users have Local Admin privileges, or your XMetaL customization is not Vista/UAC compatible (eg. writes data to Program Files folders), or if you want to enable disabled features, you must set the following variable in the XMetaL configuration file (xmetal.ini):
user_setting_mode=default // Use this value for local-admin environments 
user_setting_mode=per_user // Use this value for limited-user environments - default setting
Note: Local Admin can modify the XMetaL settings and behavior. This will affect all the users.

Desktop installation

The installer includes the following components:
  • XMetaL Author Enterprise 7.0
  • DITA Open Toolkit 1.5.4
  • DITA For Publishers, updated 8 January 2012
  • RenderX XEP 4.18 build 20100322

System requirements

  • Microsoft Windows XP*, Vista, 7 (32-bit and 64-bit), or Server 2008

    * Support for Windows XP will be deprecated after this version of XMetaL Author.

  • Pentium 133 MHz processor
  • 256 MB of available RAM (512 MB recommended)
  • Color display with a minimum resolution of 1024 x 768 or higher
  • Minimum 500 MB of disk space (800 MB recommended)
  • Microsoft Internet Explorer, version 6.00.2600.0000 or later

Special note for Windows Vista and Windows 7 installations: If you are installing the software from a Limited User account, you must provide an Administrator ID and password in order to run the XMetaL Author installer.

Special note for Windows XP installations: On computers without the Microsoft .NET Framework installed, the installation of XMetaL Author will take more time than usual to complete. To speed up the installation time, the following components of .NET Framework can be be installed beforehand and MUST be installed beforehand if you are using the "XMetaL Author Enterprise.msi":

Optional additional software

The following additional software is required for generating output and page previewing for DITA documents:

  • Microsoft HTML Help Workshop (needed for creating CHM deliverables)
  • Adobe Acrobat (needed for previewing PDF deliverables)
  • Adobe Digital Editions (needed for previewing ePUB deliverables)
  • Amazon Kindlegen 1.2 (needed for creating Kindle/mobi deliverables)
  • Amazon Mobipocket Reader (needed for previewing Kindle/mobi deliverables)
  • Eclipse PDE (needed for creating Eclipse deliverables)
  • Sun JavaHelp tools (needed for creating JavaHelp deliverables)

Before you begin

You must remove all previous versions of XMetaL Author before you install this version.

Licensing and Product Registration

Registering XMetaL author is required in order for the software to be fully licensed. The license information required for registration is provided by a license file, or by a licensing server at your company.

When XMetaL is started without a full license, you will be prompted with three options:
  • I have a license file - Allows you to insert a license file. Choose this option if you have been supplied with a license file. Possible names for the license file include xmetal.lic and XMLS.lic.
    Note: The system administrator can generate a license file, XMLS.lic, from the on-site XMetaL Licensing Server (XMLS).
  • My company has a licensing server - Allows you to enter information in order to connect to an on-site licensing server.
  • Continue Trial - Allows you to continue with the trial version of XMetaL. The trial lasts 30 days from the time of installation.

Uninstalling the software does not unregister the software from an XMetaL License Server.

If you have registered the software using direct licensing (XMdLS) then the software should be unregistered prior to uninstalling. This can be done from within the XMetaL software (Help > Licensing ). If you do not do this prior to uninstalling you will need to contact JustSystems and ask to have this computer's license revoked by providing the machine name.

If you are running your own XMetaL License Server (XMLS), you may unregister the software from withing the XMetaL software (Help > Licensing), or you may revoke the license from within the XMLS server.

To install XMetaL Author

  1. Double-click the .exe file (setup.exe if you received XMetaL Author on disk).
  2. Click Install XMetaL Author and proceed with the installation.

Per-User Deployment of DITA Open Toolkit, Samples and Customizations

The DITA Open Toolkit included with XMetaL Author is required to be deployed separately for each end user. XMetaL Author automatically deploys a per-user copy of the toolkit the first time the end user generates output or does a page preview of a DITA document. Samples files installed in the Program Files folder are also deployed on a per-user basis. Customization files may also be deployed on a per-user basis if they are initially deployed in the Program Files folder.

If you need to re-deploy the DITA Open Toolkit, remove the following folder for each user:

  • %systemdrive%\Documents and Settings\{user}\Application Data\SoftQuad\XMetaL Shared

If you need to re-deploy samples, remove the following folder for each user:

  • %systemdrive%\Documents and Settings\{user}\My Documents\XMetaL\Samples

If you need to re-deploy customization files deployed in the Program Files folder, remove the corresponding sub-folder for each customization for each user. Note that the folder structure within the following folder mimics the folder structure of the customization files:

  • %systemdrive%\Documents and Settings\{user}\Application Data\SoftQuad\XMetaL\7.0\gen

Re-integrate DITA specializations

If you have specializations, you need to re-integrate them after installing. By default, they will be setup as DITA 1.2 specializations. Adjust DITA Options if DITA 1.1 is needed. Follow these steps:

  1. Start XMetaL Author.
  2. Select Tools>Select Specialized DITA DTD and add your specialized DTD.
  3. Using a text editor, copy your specialized typemod entities from the backup copy of dcspecialized-typemods.ent and add them to ..\Author\DITA\DITA_1.2_DTD\dcspecialized-typemods.ent.
  4. Using a text editor, make any CSS, MCR, or CTM specialization changes using your backup copies.

Note: On Vista or newer with UAC enabled, you must log-in as Administrator or run XMetaL as Administrator.

Update DocApp

Note for XMetaL Author Enterprise for Documentum Webtop users: To see all the enhancements and changes for DITA, please ensure that the DocApp is updated accordingly. Updated DocApps are made available with the XMetaL Author 7.0-compatible release of XMetaL Author Enterprise for Documentum Webtop.

Re-integrate DITA-OT plug-ins

If you have DITA Open Toolkit plug-ins, you must re-integrate them after installing. Follow these steps:

  1. Open a command window at C:\Program Files\Common Files\XMetaL Shared\DITA_OT.
  2. On the command line type ant -f integrator.xml and press Enter.
  3. Copy DTDs as needed.


  • Do not start XMetaL Author until you have completed these steps.
  • Administrator privileges are required.
  • The "Idiom plug-in" (PDF2) is already integrated with the copy of the DITA OT deployed with XMetaL Author Enterprise.
  • Refer to documentation included with plug-ins you need to integrate. They may specify where the plug-in expects to be placed in relation to the DITA OT. Follow any other special instructions included with the plug-in.

Reinstalling or uninstalling XMetaL Author

You can re-run the installer from the Add/Remove Programs Control Panel.

If you have already installed XMetaL Author, the installer gives you various options if you run it again, including the option to uninstall XMetaL Author (see below).

Note: If you wish to use the copy of XMetaL Author on another computer, you will need to unregister XMetaL Author before uninstalling. See Licensing and Product Registration.

To access the Maintenance installer

  1. Choose Settings from the Start menu, and then Control Panel.
  2. Double-click Add/Remove Programs.
  3. Select XMetaL Author.
  4. Click Change/Remove. If you have already successfully installed this version of XMetaL Author, a dialog box appears with two options: Repair and Remove.
  5. Enable an option and click Next.


Select Repair if you suspect that the currently installed product has become corrupted in some way. Repair reinstalls the same set of components installed in the previous installation.
Note: The files that you downloaded must still be available if you choose this option.

In some cases there may be two or more choices that the installer can make when installing certain components. In this situation a dialog box appears asking for your preference.


Select Remove if you want to uninstall the complete product.
  • This removes all product files (except for files that exist in the WINSYS folder and which may be shared by other products), product shortcut icons, and product registry settings that were created when the product was first installed.
  • The registry key HKEY_CURRENT_USER\Software\SoftQuad\XMetaL x.x, which was created whenever you ran the XMetaL Author application, is removed along with all its sub-keys.
  • Some types of User personal settings are also removed. These data are created by XMetaL Author and not meant to persist from installation to installation. These types of data are removed from the user's personal settings folder (usually C:\...\Application Data\SoftQuad\XMetaL\... ): *.tbr, xmetal*.ini.
Other types of user data, such as files that were created directly by the user or that contain preferences that a user might want to re-use in a later version installation, are not removed at uninstallation time. If you want to remove them, you must delete them manually after uninstallation has completed. Such files may exist here:
  • Files that the user has created directly in the XMetaL installation folder.
  • Files in the User's personal settings folder. These may include preference data files such as *css, *.mcr.
Note: If you wish to use the copy of XMetaL Author on another computer, you will need to unregister XMetaL Author before uninstalling. See Licensing and Product Registration.

Silent installer

You can install XMetaL Author silently from the command line. If you obtained a single .exe file (sometimes referred to as the "web installer") you need to unpack it to obtain the "real" installer as follows:
Note: If you obtained XMetaL Author on CD you can skip this section.

  1. Run the installer's .exe file.
  2. When you are prompted for a location to unpack the installer to, specify a location you can easily locate and interact with at a command prompt.
  3. The installer will be unpacked to the location you specified and the dialog box should say "Extracting Files" (or something similar). You will know all files have been unpacked when the "real" installer has launched itself and is displaying a splash screen with the XMetaL logo and options similar to the following:
    • View Installation Guide
    • Install XMetaL Author
    • Exit
  4. Terminate this process once all files have been unpacked by selecting the Exit option.
  5. Confirm the location you specified in step 2 contains a number of folders and files, including a file called setup.exe and possibly a file called autorun.inf among others. These files and folders are what you would obtain if you obtained the product on CD.

You will need to use the XMetaL Author Enterprise.msi file under the xmetal folder to install XMetaL Author silently. Using a license file with the silent installer is optional. If the license file is named xmetal.lic and is placed in the same folder as the XMetaL Author Enterprise.msi file, the installer will automatically use it. Use the XMETAL_LICENSE_PATH parameter when a license file is not in the same folder as the MSI file or the name of the license file is not xmetal.lic. If a license file is not used, the XMETAL_LICENSE_PATH is not required. The license file is provided by JustSystems or by your system administrator.

Use the following syntax to silently install:
msiexec /i "path of XMetaL Author Enterprise.msi file" /qn XMETAL_LICENSE_PATH=path of license file
Note: The XMETAL_LICENSE_PATH parameter is required only when the license file is not in the same folder as the MSI file or the name of the license file is not xmetal.lic.
Use the following syntax to silently uninstall:
msiexec /x "path of XMetaL Author Enterprise.msi file" /qn
To get more options pertaining to the silent installation, run msiexec in another Command Prompt without any options.
Note: If you wish to use the copy of XMetaL Author on another computer, you will need to unregister XMetaL Author before uninstalling. See Licensing and Product Registration.

Installing dictionaries

This release of XMetaL Author automatically installs all supported languages for spell checking and the thesaurus including the following

Spell Checker:
  • Afrikaans
  • Catalan
  • Czech
  • Danish
  • Dutch
  • English-Australian
  • English-Canadian
  • English-U.K.
  • English-U.S.
  • French-Canadian
  • French-National
  • Galacian
  • German-National
  • German-Swiss
  • Greek
  • Icelandic
  • Italian
  • Norwegian
  • Portuguese-Brazilian
  • Portuguese-National
  • Russian
  • Slovak
  • Sotho
  • Spanish-American
  • Spanish-National
  • Swedish
  • Tswana
  • Turkish
  • Xhosa
  • Zulu
  • US English
  • UK English
  • Danish
  • Dutch
  • French
  • German
  • Italian
  • Norwegian
  • Portuguese
  • Spanish
  • Swedish

Installing XMetaL Author without Administrative Privileges

The XMetaL Author Installer Setup program warns you if you do not have permission to install XMetaL Author (for example, if you are logged in as a normal or restricted user). The solution is to install XMetaL Author on Windows by logging in as a user who has administrator privileges.

Citrix-compatible installations

XMetaL Author is now certified on Citrix Metaframe Presentation Server 4.0. The Citrix-compatible version of XMetaL uses the MSI-type installer and has specific installation prerequisites. There are also some minor functional differences in the software. These and other differences are detailed below.

The Citrix Installation Manager will install the MSI installer silently, so there is no user interaction.

The MSI installer cannot be modified or repaired through Add/Remove Programs. It should be removed only from the Citrix Installation Manager.

MSI installer prerequisites

The following components must be installed on your server before XMetaL Author will operate correctly:
Note: Version numbers noted above are minium versions.

Silent installer

You can create a silent installer packages for Citrix installations. To create a silent installer from Installation Manager, add the product license path as a command line parameter.
  1. In the Citrix management console, select the XMetaL MSI installer.
  2. Click Yes to add command line parameters.
  3. In the MSI Attributes dialog, specify the license path and all-users option using the following command line option:
    XMETAL_LICENSE_PATH=path of license file

No command line parameters are required to un-install.

Drive remap support

XMetaL Author has been tested and operates properly when the Citrix drive remap feature is configured. Please ensure XMetaL Author is installed only after drive remap has been applied.

Optional additional software

The following additional software is required for the generating output and page previewing:

  • Microsoft HTML Help Workshop (needed for creating CHM deliverables)
  • Adobe Acrobat (needed for previewing PDF deliverables)
  • Adobe Digital Editions (needed for previewing ePUB deliverables)
  • Amazon Kindlegen 1.2 (needed for creating Kindle/mobi deliverables)
  • Amazon Mobipocket Reader (needed for previewing Kindle/mobi deliverables)
  • Eclipse PDE (needed for creating Eclipse deliverables)
  • Sun JavaHelp tools (needed for creating JavaHelp deliverables)

Citrix 'Publish Application' recommended settings

In Citrix environments, it is expected that the administrator will setup XMetaL Author prior to publishing the application to the Citrix users. If specializations or some pre-configuration is required using these features, the Citrix admin needs to toggle the 'user_setting_mode' variable (see Configuring XMetaL Author).

The Citrix Presentation Server requires you to do a 'publish application' in order to make XMetaL Author visible to your end users. The following settings are recommened or suggested minimum settings:
Application Limits: Check 'Allow only one instance of application for each user'
Application Appearance: Session Window Size: 1024x768
Application Appearance: Colors: High Color (16-bit) or better
If you encounter problems, it is possible that the XMetaL document customization you are using is not Citrix-aware. In addition to the above 'Publish Application' settings, adjust the following setting:
Application Location : Check 'Isolate Application'