Upgrade Best Practices

When upgrading to Texis version 8 from a version 7 or earlier installation, existing scripts (e.g. customer-written, besides Webinator scripts which are automatically updated with Texis) may not run with the new default syntax version (see caveats below). Thus, the recommended upgrade procedure for Texis version 8 over an existing version 7 install is as follows (see following sections for discussion of e.g. syntaxversion which is new in Texis 8):

1. Stop all running Texis scripts and services

2. Install version 8

3. Set texis.ini setting [Texis] Compatibility Version to 7.nn

   This allows existing version 7 syntax scripts to run under Texis version 8, and also keeps major (but not all) version 8 changes suppressed. The value should be the major.minor version of the existing Texis installation. See this setting in the Texis conf/texis.ini section of the Texis manual for details (or here for its effects). This is a temporary measure during the upgrade, and should be removed soon afterwards.

4. Restart Texis services, test functionality

   At this point, existing scripts should be runnable with Texis 8 (due to [Texis] Compatibility Version rollback above). However, test scripts/applications to be sure, and check for potential issues not covered by this setting.

5. Upgrade existing scripts to syntax version 8

   Once the system is stable, upgrade existing scripts individually to version 8 syntax so they can take advantage of it, and so they will continue to run when a future upgrade (that may no longer support syntax version 7) is installed. This can be done at leisure, but should be completed soon after upgrading to avoid potential future problems.

   To translate a script from version 7 syntax to the current syntax version (8), run texis -translate-from-version 7 example.vs; see here for details. Note that ambiguous/unknown situations the translator cannot handle may still require hand-editing; in particular, see comments tagged translated-from-version in the output script.

   Each translated script should temporarily start with a <!-- pragma syntaxversion 8 -> directive (here), and an <entryfunc> that sets <vxcp compatibilityversion 8> (here). This is because the system default syntax and compatibility versions are temporarily 7 due to the Compatibility Version change above, so version 8 must be temporarily set in each script as it is translated. The --translate-from-version 7 option should have done this automatically.

   Test each translated script; in particular behavior affected by the caveats in the next sections (here).

6. Remove temporary settings

   Once all scripts are translated to version 8 and tested, the following temporary transition measures should be removed:

   • The temporary [Texis] Compatibility Version setting in texis.ini

   • The temporary <!-- pragma syntaxversion 8 -> directives in scripts

   • The the temporary <vxcp compatibilityversion 8> settings in scripts