XMetaL® Author Enterprise 13.0 Install Readme


Important Digital Signature Changes

Effective January 1, 2016, Microsoft has mandated that software vendors digitally sign their products using the SHA256 algorithm. All XMetaL 11.0 and newer products are signed using the mandated SHA256 algorithm. As a result of using this new signing algorithm, attempts to install the software on older unsupported Windows systems such as Windows XP will fail. Please confirm the system requirements are met.


Important License Changes for version 7.0 and 8.0 users

With the release of versions 9.0 through 13.0, the XMetaL software no longer requires an Internet connection to register or unregister a per-seat license. Users with a version 7.0 or 8.0 license file should receive a new license file (e.g. XMEE.lic) as required to activate this software.

For concurrent licenses, a new version of the XMetaL License Server (XMLS) software must be installed. The new XMLS software does not require an Internet connection to register or unregister. A new product license file (e.g. XMLS-XMEE.lic) must be added to your XMLS server. See the new XMLS User Guide for more details.

Note: Older .lic files are incompatible with this version.

Contact your JustSystems Sales representative if you have further licensing-related questions.


Important .EXE and .INI file name change

With the release of version 10.0, the XMetaL executable and configuration file names no longer incorporate a version number. Instead of xmetal10.exe or xmetal10.ini, the file names are simply xmetal.exe and xmetal.ini.


Installation Notes

These installation notes cover the following XMetaL Author Enterprise installations:

Limited User vs. Local Admin accounts

All installations of XMetaL Author are pre-configured to operate in an environment where end-users are assumed to 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 (right-click and choose ‘Run as Administrator’) warn the user before proceeding or are disabled.

Here are the features that display a warning:

  • 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

Regardless of account privileges, the following processes and features are disabled:

  • Drag-and-drop operations to 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

Alternatively, you can use these features by running XMetaL Author in Administrator mode. Follow these steps:

  1. Right-click on the XMetaL Author shortcut and choose ‘Run as Administrator’.
  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-administrator, users MUST chose ‘Run as Administrator’.

Configuring XMetaL Author for Local Admin privileges

XMetaL Author Enterprise is installed with the assumption that users have Limited User account privileges under Windows. If you need to set up DITA specializations for your end users, or if you want to enable features that are otherwise disabled for Limited Users you must set the following variable in the XMetaL Author configuration file (xmetal.ini): user_setting_mode=default Local Admin users very familiar with the product may continue to work with XMetaL Author Enterprise in this mode, however, we recommend that it only be used to accomplish tasks that cannot be done otherwise and that the default setting be restored once these tasks are accomplished. The default setting is the "per-user" mode, which is set as follows: user_setting_mode=per_user


Desktop installation

The installer includes the following components:

  • XMetaL Author Enterprise 13.0
  • DITA Open Toolkit Release 3.0.2
  • DITA Open Toolkit Release 2.4.4
  • DITA Open Toolkit Release 2.0
  • RenderX XEP 4.18
  • ISO Schematron
  • Saxon-CE 1.1

System requirements

  • Microsoft Windows Vista, 7, 8, 8.1, 10 or 2008/2012 Server
  • 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 615 MB of disk space (800 MB recommended)
  • Additional memory may be required to generate some types of output using the DITA Open Toolkit.
  • Microsoft Internet Explorer 11
  • MSXML3.dll 8.0.7820.0 or newer (MSXML 3.0)
  • MSXML6.dll 6.20.5002.0 or newer (MSXML 6.0)

Special note for 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.

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)
  • Eclipse PDE (needed for creating Eclipse deliverables)
  • Sun JavaHelp tools (needed for creating JavaHelp deliverables)

Before you begin

You must have a 9.0 compatible or newer license file to install this version. If you do not have a license file, contact Sales.

If you are installing this version onto a computer with an existing version of XMetaL Author Enterprise, please be aware that the software does not support installing or running two versions in the same Windows installation. If you somehow manage to do so neither version will function properly.

If your current version is:

  • 5.5 or earlier - Existing version must be manually removed before installing this version.
  • 6.0 through 12.0 - These older versions will automatically be removed by this installer providing the platform is the same (i.e. 32 vs 64-bit).

If you must use two versions of the software on the same physical computer you may wish to install one version in a virtual machine running inside software such as VMWare, Virtual PC, or VirtualBox.

If you switch to another program while the XMetaL Author Enterprise license activating dialog is in the foreground, you will not be able to switch back to it using Alt+tab. Minimize all other applications in order to reveal the licensing activation dialog once again.

If you have specializations, make copies of the following files and folders and note that n.n can be either "1.3", "1.2" or "1.1":

  • %PROGRAMFILES(x86)%\XMetaL\Author\DITA\n.n\XACs\{specialization folders}
  • %PROGRAMFILES(x86)%\XMetaL\Author\DITA\DITA_n.n_DTD\dcspecialized-typemods.ent
  • %PROGRAMDATA%\SoftQuad\XMetaL\Shared\DITA_OT\{your-plugins}

Note: If you want to keep a previous version of the DITA Open Toolkit, rename the following folder before you install: %PROGRAMDATA%\SoftQuad\XMetaL\Shared\DITA_OT. If you have added any plug-ins or made customization such as XSLT changes, make sure to do a backup. For more information about specifying parameters, see the XMetaL Author Enterprise User’s Guide.

Licensing and Product Activation

Activating your XMetaL Author Enterprise software is required in order to be fully licensed to use the software. The license information required for activation is provided by a license file.

When XMetaL is started without a full license, you will be prompted with three options:
  • Activate - Allows you to select a license file. Choose this option if you have been supplied with a license file (e.g. XMEE.lic).
  • Continue Trial - Allows you to continue with the trial version of XMetaL. The trial lasts 30 days from the time of installation.
  • Exit - Closes XMetaL.

To install XMetaL Author

  1. Double-click the web installer file, XMAU-ENTERPRISE-13.0-x64.exe for 64-bit native or XMAU-ENTERPRISE-13.0-x86.exe for 32-bit native (or setup.exe if you received the software on cdrom).
    Note: We recommend using the x86 installer unless you are integrating with x64 software specifically.

  2. Click Install XMetaL Author and proceed with the installation.

Per-User Deployment of Samples and Customizations

Samples files installed in the Program Files folder are deployed on a per-user basis by choosing the Help > Samples submenu item of interest. 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 samples, remove the following folder for each user:

  • %userprofile%\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:

  • %userprofile%\Application Data\SoftQuad\XMetaL\13.0\gen

The full (expanded) path for %userprofile% varies depending on your Windows version and user account configuration, but generally follows this pattern:

C:\Users\{account name}\Application Data

Note: The %appdata% folder is a hidden folder on most Windows accounts.

Re-integrate DITA specializations

If you have specializations, you need to re-integrate them after installation. 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.3_DTD\dcspecialized-typemods.ent" or "..\Author\DITA\DITA_1.2_DTD\dcspecialized-typemods.ent" or "..\Author\DITA\DITA_1.1_DTD\dcspecialized-typemods.ent"
  4. Using a text editor, make any CSS, MCR, or CTM specialization changes using your backup copies.

Note: You must log in as an 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 13.0-compatible release of XMetaL Author Enterprise for Documentum Webtop.

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 options to Remove or Repair XMetaL Author (see below).

To access the Maintenance installer

  1. Open the Windows 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.

Repair

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 the original installer unpacked 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.

Remove

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 %APPDATA%\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.

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

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.

Important note: If you intend to use the DITA Open Toolkit on a Citrix installation, you must configure per-user deployment of the DITA Open Toolkit. See Shared versus per-user DITA Open Toolkit deployments for details.

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.

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

Thesaurus:

  • US English
  • UK English
  • Danish
  • Dutch
  • French
  • German
  • Italian
  • Norwegian
  • Portuguese
  • Spanish
  • Swedish

Configuring the spell checker to use Hunspell compatible dictionaries

This release can be configured to use Hunspell compatible dictionaries for spell checking. These can be used to extend or replace the languages included with the spell checker. They are the same standard Hunspell spell checking dictionary files supported by OpenOffice™ and some other applications.

Most of these files come with their own EULA and so it is up to you to obtain and deploy compatible .DIC and associated .AFF files for each language you want XMetaL Author to use. For additional and updated information on this subject please see Obtaining and Using Hunspell Compatible Dictionaries with XMetaL Author

Configuration:

Once you have a compatible .DIC file (and optional .AFF file) use the following the procedure to configure XMetaL Author to use them.

  1. Copy the Hunspell compatible dictionary file(s) to a computer with XMetaL Author installed. You may place these files in any folder you like. Note: For XMetaL Author to locate and use an .AFF file it must have the same name and be in the same folder as the .DIC file. In some cases this may mean you will need to rename the .AFF file to match the .DIC file.
  2. Launch XMetaL Author.
  3. Open any XML or SGML document in Tags On or Normal view (a document must be open to enable the Spell Checker).
  4. Open the spell checker dialog (labelled "Writing Tools") by selecting Tools > Spell Checker. If you are prompted to close the spell checker click the "No" button.
  5. Perform the following substeps only if the language is NOT in the list of default supported spell checking languages:
    1. Open the "Select Language" dialog by clicking Options > Language.
    2. Click the "Add..." button.
    3. Type a new "Language Code" and "Description" and click OK. You may invent these yourself. The only requirement is that the Language Code is not already used by a default language.
    4. From the "Language" list, select the new entry for the "Language Code" you just created.
    5. Enable (check) the "Save as default Writing Tools language" checkbox.
    6. Click OK.
    7. A dialog titled "Unsupported Language..." should appear.
    8. Click the "Find File..." button then browse to and select your Hunspell compatible .DIC file.
    9. Close the Writing Tools window.
  6. Perform the following substeps only if the language is ALREADY in the list of default supported spell checking languages:
    1. Open the "Main Word Lists" dialog by clicking Options > Main Word Lists.
    2. Click the "Add List..." button, and then browse to and select your Hunspell compatible .DIC file.
    3. (optional) Disable (deselect the checkbox) any files you do not wish to use for spell checking for this language. XMetaL Author will use all enabled files when looking for a match.
    4. Close the Main Word Lists dialog.
    5. Close the Writing Tools dialog.

Restart XMetaL Author to start spell checking with the newly added Hunspell dictionary.

If the language you have added a Hunspell dictionary for is not set as the "default Writing Tools" language, you may wish to set it. There are other ways to spell check (using xml:lang and APIs) so this is not necessarily the case. Please refer to Help for information on spell checker functionality.

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 minimum versions.

Silent installer

You can create a silent installer packages for Citrix installations. To create a silent installer from Installation Manager, add the product serial number 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 serial number and all-users option using the following command line option:
    XMETAL_LICENSE_PATH=path of license file

To enable per-user deployments of the DITA Open Toolkit, please see Shared versus per-user DITA Open Toolkit deployments.

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)
  • 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 set up 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 recommended 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'

Switching between DITA Open Toolkit versions 3.0.2, 2.4.4, and 2.0

By default, version 3.0.2 of the DITA Open Toolkit (DOTK) is configured for Generate Output operations within the software. If you require a previous version to be used, version 2.4.4 or 2.0, there is a configure output variable that needs to be hidden in order to make version 2.4.4 or 2.0 the default for Generate Output operations.

Follow the steps below to change the "active" DOTK to v2.4.4:

  • Launch the software
  • Select the "Configure Output..." menu item from the Tools menu. A dialog should appear titled "Configure Output Options".
  • Activate the "Advanced" tab in the "Configure Output Options" dialog.
  • Change the "DITA_OT_DIR" name to "_DITA_OT_DIR" within the "Other output parameter (<name>=<value> pairs):" multi-line editbox.
  • Change the second "_DITA_OT_DIR" name to "DITA_OT_DIR" within the "Other output parameter (<name>=<value> pairs):" multi-line editbox.
  • Click OK. Now the system is configured to use the v2.4.4 DOTK release for generating output. Restarting the software is not necessary.

Follow the steps below to change the "active" DOTK to v2.0:

  • Launch the software
  • Select the "Configure Output..." menu item from the Tools menu. A dialog should appear titled "Configure Output Options".
  • Activate the "Advanced" tab in the "Configure Output Options" dialog.
  • Change the "DITA_OT_DIR" name to "__DITA_OT_DIR" within the "Other output parameter (<name>=<value> pairs):" multi-line editbox.
  • Change the third "__DITA_OT_DIR" name to "DITA_OT_DIR" within the "Other output parameter (<name>=<value> pairs):" multi-line editbox.
  • Click OK. Now the system is configured to use the v2.0 DOTK release for generating output. Restarting the software is not necessary.

Shared versus per-user DITA Open Toolkit deployments

The default DITA Open Toolkit (DOTK) installation and execution location has changed with this release. For some types of installations such as on Citrix, you will need to adjust the execution location via the DITAOT_PER_USER option described below.

By default, the DOTK will be installed and run from here: %ALLUSERSPROFILE%\SoftQuad\XMetaL\Shared\DITA_OT

For installations requiring per-user deployment of the DOTK (re: Citrix), please run the installer choosing one of the following command-line options:

  • setup.exe /v "DITAOT_PER_USER=true"
  • msiexec /i "XMetaL Author Enterprise.msi" DITAOT_PER_USER=true

For per-user (Citrix) installations, the DOTK will be installed to %ALLUSERSPROFILE%\SoftQuad\XMetaL\Shared\DITA_OT but run from here: %APPDATA%\SoftQuad\XMetaL\Shared\DITA_OT

To adjust the behavior after installing, confirm XMetaL Author Enterprise is not running, delete %APPDATA%\SoftQuad\XMetaL\13.0\print_local.xml, and change the value of the dita_ot_per_user INI variable in the %PROGRAMFILES%\XMetaL 13.0\Author\xmetal.ini file:

  • dita_ot_per_user=true - use this setting for per-user DOTK
  • dita_ot_per_user=false - use this setting for shared DOTK

Known Issues

XMetaL Author displays script error messages at startup after uninstalling XMetaL Developer 9.0

Due to bugs within the XMetaL Developer 9.0 installer, certain registry entries are removed by mistake. To fix this issue, go to the Add/Remove Programs control panel and repair the XMetaL Author installation.

DITA dialogs or spell-checking stops working after uninstalling x64 XMetaL product

Certain XMetaL product features are implemented in part by DLLs that are shared with other XMetaL products. When a mix of x86 and x64 XMetaL products are installed on the same machine, uninstall one of them can cause certain features to stop functioning in those XMetaL products still installed on the system.

To correct this issue, go to the Add/Remove Programs control panel, select the XMetaL product that is not working, click the "Change" option and wait for the installation wizard to appear. After the installation wizard appears, follow the wizard's instructions and choose the "Repair" option when presented.