Home Forums DITA and XMetaL Discussion How to add custom footer text for PDF? Reply To: How to add custom footer text for PDF?

Derek Read

Reply to: How to add custom footer text for PDF?

The previous instructions in this post were meant for 5.1 (I took a guess because much of our install-base is still running that version).

XMetaL Author Enterprise 5.5 DITA OT “Deployment”

NOTE: this post applies to the 6.0 release as well as this functionality has not been altered.

With XMetaL Author Enterprise 5.5 we have implemented a method of deploying the DITA Open Toolkit so that even “Limited Users” (ie: hopefully anybody) can run it. The XMetaL Author Enterprise 5.5 installer places a copy of the DITA OT in %PROGRAMFILES%. However, the DITA OT needs to write to the location it is installed to so that is a problem. For “Limited Users” %PROGRAMFILES% is typically read-only so running the DITA OT in that location will fail unless you have write permission for that folder. Most “Adminstrators” have this right (but not all and Vista UAC can also be troublesome). We also needed to allow multiple users to run the DITA OT as a Windows machine allows multiple users to use it (by logging in with different user accounts).

To get around these issues, the first time you generate output XMetaL Author Enterprise 5.5 first deploys a copy of the DITA OT into the Windows %APPDATA% folder structure, which is separate for each logged in user of the machine.

The closest I can get to a human readable (less geeky) path for %APPDATA% is the following:

English XP (common, but your IT dept may set otherwise) =
C:Documents and SettingsApplication Data

English Vista (common, but your IT dept may set otherwise) =
C:UsersAppDataRoaming
or
C:UsersAppData
or
C:ProfilesAppData

To all of the above add the following to the end to find the DITA OT folder on your system:
SoftQuadXMetaL Shared

Some examples for %APPDATA% + deployed copy of the DITA OT:
C:Documents and SettingsApplication DataSoftQuadXMetaL Shared
C:UsersAppDataRoamingSoftQuadXMetaL Shared
C:ProfilesAppDataSoftQuadXMetaL Shared

Typical example for %PROGRAMFILES% + installed copy of the DITA OT:
C:Program FilesCommon FilesXMetaL Shared

The contents of the folder %PROGRAMFILES%Common FilesXMetaL Shared will be copied into %APPDATA%SoftQuadXMetaL Shared the first time you generate output.

So, having (tried) to explain where you can find these things, you have several options for modifying the DITA OT for your end users:

A. Modify an already deployed copy of the DITA OT
This only affects one user on this computer. Other logged-in users of the machine will not see these changes as they will have their own deployed copy of the DITA OT.
1. Install XMetaL Author Enterprise 5.5.
2. Open a DITA document (topic or map).
3. Generate output. This is when the DITA OT is first deployed to the currently logged in user's %APPDATA% folder.
4. Locate the files you wish to modify in the deployed copy of the DITA OT and modify them as desired. All subsequent calls to generate output will use the same deployed copy of the DITA OT.

B. Modify the installed copy of the DITA OT before deployment
This will affect any logged in user that is allowed to run XMetaL Author Enterprise. Any user generating output will receive your modified copy of the DITA OT as part of the very firstĀ  deployment phase for that user.
1. Install XMetaL Author Enterprise 5.5. Do not generate output using the DITA OT via XMetaL Author Enterprise's UI.
2. Locate the files you wish to modify in the installed copy of the DITA OT inside %PROGRAMFILES% and modify them as desired. Now any user that generates output, provided they have not already done so, will have your modified copy deployed to their %APPDATA% folder.

C. Modify the installed copy after deployment and force redeployment
This will still work even if a logged in user has done either of the above.
1. Install XMetaL Author Enterprise 5.5.
2. Locate the files you wish to modify in the installed copy of the DITA OT inside %PROGRAMFILES% and modify them as desired.
3. Tell any user that wishes to deploy your modified version of the DITA OT to add the following parameter to Tools > Configure Output… > Advanced (tab) > Other output parameters (textbox): cmd_dita_ot_per_user_version =
needs to be an integer greater than the one they used last (starting with at least 1). Using the date in the form yyyymmdd (ie: 20090309) is one good way to keep track of this, otherwise just add 1 to the last number specified.
4. The next time any user generates output (provided they have performed step 3) they will be asked if they wish to update the DITA OT. They must answer “OK” to this prompt. The DITA OT will then be redeployed from the %PROGRAMFILES% location (which you modified) to the %APPDATA% location before running it from the %APPDATA% location.

Administrators automating this process may which to view this post: [url=http://forums.xmetal.com/index.php?topic=180.0]http://forums.xmetal.com/index.php?topic=180.0[/url]

D. Modify the installed copy and delete any previously deployed version
1. Install XMetaL Author Enterprise 5.5.
2. Locate the files you wish to modify in the installed copy of the DITA OT inside %PROGRAMFILES% and modify them as desired.
3. Delete the copy of the DITA OT deployed to the %APPDATA% folder.
4. The next time output is generated XMetaL Author Enterprise will see that there is no deployed copy of the DITA OT and will deploy it.

Note: This is all true only when the following default setting in present in the xmetal55.ini file user_setting_mode=per_user. That INI value should not be altered for the vast majority of installations. The XMetaL Author Enterprise 5.5 install-readme.html file contains information on the usage of this INI variable.

The following Wikipedia page contains more information on [url=http://en.wikipedia.org/wiki/Environment_variable#Default_Values_on_Microsoft_Windows]Windows Environment Variables[/url].

Reply

Products
Downloads
Support