Add info on migrating to v2.x

[infotexture]

To assist users in migrating from OT v1.x to v2.x, the documentation should include an overview of the types of changes required to update existing projects for use with v2.0.

Topics may include:

• Changes in Ant target names
• Deprecated XSLT templates
• Updating existing Ant build scripts
• Configuration via properties files vs. environment variables, $DITA_HOME, etc.

Separate topics should be created with migration info for each 2.x release:

• 2.0
• 2.1
• 2.2
• 2.3

[shaneataylor]

I documented one issue for migration to 2.1 in my fork in branch "issue29." Obviously there are more issues, and more versions, but it's a small start.

[keberlein]

I just began migrating some PDF plug-ins to work with DITA-OT 2.2, and am getting messages that the insertVariable template has been deprecated. Searched the docs; did not get any hits other than a topic on "Migrating to Release 1.8'>

[stefan-jung]

For migrating PDF plugins, I'd recommend in the docs to generate a new plugin using the DITA generator and then migrate template by template and test everything.

[keberlein]

@xephon2 Jarno's generator is great -- and very useful -- but if you have existing plug-ins with extensive comments (not to mention customizations!) that you want and need to retain, using it to generate a brand-new plug-in is not realistic.

[shaneataylor]

Kris, I've drafted info about the issue you saw in my fork.

[shaneataylor]

Although I'm not ready to open a pull request, if anyone is interested in the info about the insertVariable template, see https://github.com/shaneataylor/docs/blob/issue29/dev_ref/migrating-to-2.1.0.dita.

[infotexture]

@xephon2 The docs will link to the DITA generator per your suggestion in #57, though I'd recommend it as a starting point for new customizations, rather than as a means of migrating existing customizations.

The generator makes extensive use of the custom.xsl files to store template overrides, which is a good way to ensure that plugins remain compatible with future toolkit versions. However, many existing customizations (especially those derived from the Idiom customization folder approach) began by modifying copies of pdf2 files and including those, rather than overriding individual templates.

Many appreciate the latter approach, as it facilitates comparisons of custom plugin content with pdf2 defaults via a simple directory comparison. In this scenario, comparing with generator output is less useful, so I wouldn't recommend using it to migrate existing customizations.

[infotexture]

The OT source code contains comments where code has been deprecated. These code comments serve as a starting point for the migration topics. As a bare minimum, we should provide a list of the templates, modes, etc. that have been deprecated in each OT version.

These lists can then be augmented with additional recommendations on the new constructs with which the deprecated calls should be replaced, as @shaneataylor has done for the insertVariable template.

I'd be happy to pull those changes in when you feel they're ready, even if there are other changes which still need to be documented — those can be addressed later in subsequent pull requests.

[stefan-jung]

@keberlein I remember I had many errors when trying to use my heavy customized 1.8.5 plugin with a 2.x toolkit. The errors did not help me to figure out to find the errors in my code. Therefore I migrated step-by-step.

What I do now (and I hope someone could explain me a more efficient way) is:

• Deploy my plugin to the new OT, generate some test publications and than check, if everything is fine. If not:
• Create a new plugin and copy all specialized templates that are based on templates that have not changed between the OT releases. This works quite nice using git diff. For example, you visualize the changes of the tables.xsl between the HEAD commit and the latest 1.x hotfix commit with this command:

git diff 5678d8c806e30154dba14cf75ec0f4350a590f13 HEAD tables.xsl

Assumption If a template has not changed in PDF2, its specialization will probably also work as it did before.

• Deploy and test the plugin. If everything is fine, copy a template, that has also changed in PDF2. Compare the changes, change something, if needed, deploy and test the plugin and repeat 3. until all templates are migrated.