34 lines
No EOL
14 KiB
HTML
34 lines
No EOL
14 KiB
HTML
<!DOCTYPE html
|
|
SYSTEM "about:legacy-compat">
|
|
<html lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta charset="UTF-8"><meta name="copyright" content="(C) Copyright 2020"><meta name="generator" content="DITA-OT"><meta name="description" content="If you have XSL transformation overrides, plug-ins or other customizations written prior to DITA-OT 3.6, you may need to make changes to ensure your overrides work properly with the latest toolkit versions."><meta name="keywords" content="upgrading, plug-ins, migrating, installing, plug-ins, upgrading"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Migrating customizations</title></head><body id="ID"><header role="banner"><div class="header">
|
|
<p>DITA Open Toolkit</p>
|
|
<hr>
|
|
</div></header><nav role="toc"><ul><li><a href="../index.html">DITA Open Toolkit 3.6</a></li><li><a href="../release-notes/index.html">Release Notes</a></li><li><a href="../topics/installing-client.html">Installing DITA-OT</a></li><li><a href="../topics/building-output.html">Building output</a></li><li><a href="../topics/input-formats.html">Authoring formats</a></li><li><a href="../topics/output-formats.html">Output formats</a></li><li><a href="../parameters/index.html">Parameters</a></li><li><a href="../topics/html-customization.html">Customizing HTML</a></li><li><a href="../topics/pdf-customization.html">Customizing PDF</a></li><li><a href="../topics/adding-plugins.html">Adding plug-ins</a></li><li><a href="../topics/custom-plugins.html">Creating plug-ins</a><ul><li><a href="../topics/plugin-benefits.html">Plug-in benefits</a></li><li><a href="../topics/plugin-configfile.html">Plug-in descriptor file</a></li><li><a href="../topics/plugin-coding-conventions.html">Coding conventions</a></li><li><a href="../topics/plugin-dependencies.html">Plug-in dependencies</a></li><li><a href="../topics/plugin-use-cases.html">Plug-in use cases</a></li><li><a href="../topics/html-customization-plugins.html">Custom HTML plug-ins</a></li><li><a href="../topics/pdf-customization-plugins.html">Custom PDF plug-ins</a></li><li><a href="../topics/globalization.html">Globalizing DITA content</a></li><li class="active"><a href="../topics/migration.html">Migrating customizations</a><ul><li><a href="../topics/migrating-to-3.6.html">To 3.6</a></li><li><a href="../topics/migrating-to-3.5.html">To 3.5</a></li><li><a href="../topics/migrating-to-3.4.html">To 3.4</a></li><li><a href="../topics/migrating-to-3.3.html">To 3.3</a></li><li><a href="../topics/migrating-to-3.2.html">To 3.2</a></li><li><a href="../topics/migrating-to-3.1.html">To 3.1</a></li><li><a href="../topics/migrating-to-3.0.html">To 3.0</a></li><li><a href="../topics/migrating-to-2.5.html">To 2.5</a></li><li><a href="../topics/migrating-to-2.4.html">To 2.4</a></li><li><a href="../topics/migrating-to-2.3.html">To 2.3</a></li><li><a href="../topics/migrating-to-2.2.html">To 2.2</a></li><li><a href="../topics/migrating-to-2.1.html">To 2.1</a></li><li><a href="../topics/migrating-to-2.0.html">To 2.0</a></li><li><a href="../topics/migrating-to-1.8.html">To 1.8</a></li><li><a href="../topics/migrating-to-1.7.html">To 1.7</a></li><li><a href="../topics/migrating-to-1.6.html">To 1.6</a></li><li><a href="../topics/migrating-to-1.5.4.html">To 1.5.4</a></li></ul></li></ul></li><li><a href="../topics/troubleshooting-overview.html">Troubleshooting</a></li><li><a href="../reference/index.html">Reference</a></li><li><a href="../topics/dita-and-dita-ot-resources.html">Resources</a></li></ul></nav><main role="main"><article role="article" aria-labelledby="ariaid-title1">
|
|
<h1 class="title topictitle1" id="ariaid-title1">Migrating customizations</h1>
|
|
|
|
|
|
<div class="body refbody"><p class="shortdesc">If you have XSL transformation overrides, plug-ins or other customizations written prior to DITA-OT
|
|
<span class="keyword">3.6</span>, you may need to make changes to ensure your overrides work properly with the latest
|
|
toolkit versions. </p>
|
|
<section class="section">
|
|
<p class="p">In some cases, you may be able to remove old code that is no longer needed. In other cases, you may need to
|
|
refactor your code to point to the modified extension points, templates or modes in recent toolkit versions.</p>
|
|
<p class="p">When migrating customizations, identify the version of the toolkit you're
|
|
currently using (base version) and the version of the toolkit you want to migrate to (target version). Then,
|
|
review all of the migration changes described in <em class="ph i">all</em> of the versions from the base through the target.
|
|
For instance, if you're currently on 2.2 and want to move to 3.3, you should review all of the changes in 2.3
|
|
through 3.3. You may want to start at the oldest version and read forward so you can chronologically follow the
|
|
changes, since it is possible that files or topics have had multiple changes. </p>
|
|
<div class="note note note_note"><span class="note__title">Note:</span>
|
|
<p class="p">DITA-OT releases follow
|
|
<a class="xref" href="https://semver.org" target="_blank" rel="external noopener">semantic versioning</a> guidelines. Version numbers use the
|
|
<code class="ph codeph"><var class="keyword varname">major</var>.<var class="keyword varname">minor</var>.<var class="keyword varname">patch</var></code> syntax, where
|
|
<var class="keyword varname">major</var> versions may include incompatible API changes, <var class="keyword varname">minor</var> versions add
|
|
functionality in a backwards-compatible manner and <var class="keyword varname">patch</var> versions are maintenance releases
|
|
that include backwards-compatible bug fixes.</p><p class="p">Custom plug-ins developed for a previous <var class="keyword varname">major</var> version may require
|
|
changes to work correctly with recent toolkit versions. Most plug-ins should be compatible with subsequent
|
|
<var class="keyword varname">minor</var> and <var class="keyword varname">patch</var> versions of the <var class="keyword varname">major</var> release for
|
|
which they were originally developed.</p></div>
|
|
</section>
|
|
</div>
|
|
<nav role="navigation" class="related-links"><ul class="ullinks"><li class="link ulchildlink"><strong><a href="../topics/migrating-to-3.6.html">Migrating to release 3.6</a></strong><br>DITA-OT 3.6 includes <span class="ph">performance enhancements such as processing in parallel and in memory, support for PDF changebars with Apache™ FOP, and an updated preview of features for the latest draft of the upcoming DITA 2.0 standard, including the <code class="keyword markupname xmlelement"><audio></code> and <code class="keyword markupname xmlelement"><video></code> elements, and the new emphasis domain</span>.</li><li class="link ulchildlink"><strong><a href="../topics/migrating-to-3.5.html">Migrating to release 3.5</a></strong><br>DITA-OT 3.5 includes <span class="ph">support for additional input resources, an alternative subcommand syntax for the <span class="keyword cmdname">dita</span> command, and an initial preview of features for the latest draft of the upcoming DITA 2.0 standard</span>.</li><li class="link ulchildlink"><strong><a href="../topics/migrating-to-3.4.html">Migrating to release 3.4</a></strong><br>DITA-OT 3.4 includes <span class="ph">an official Docker container image, a separate plug-in for PDF indexing, a new option to skip HTML5 cover pages, and initial support for project files that allow you to define multiple deliverables in advance, and publish them all at once</span>.</li><li class="link ulchildlink"><strong><a href="../topics/migrating-to-3.3.html">Migrating to release 3.3</a></strong><br>DITA-OT 3.3 includes <span class="ph">new attribute sets for HTML5 customization, support for custom integration processing, rotated table cells in PDF output, and hazard statements in HTML output</span>.</li><li class="link ulchildlink"><strong><a href="../topics/migrating-to-3.2.html">Migrating to release 3.2</a></strong><br>DITA-OT 3.2 includes <span class="ph">new command-line options, support for RELAX NG parsing and validation, preliminary processing for the XDITA authoring format proposed for Lightweight DITA, and a plug-in registry that makes it easier to discover and install new plug-ins</span>.</li><li class="link ulchildlink"><strong><a href="../topics/migrating-to-3.1.html">Migrating to release 3.1</a></strong><br>DITA-OT 3.1 includes <span class="ph">support for DITA 1.3 SVG domain elements, enhanced <code class="keyword markupname xmlelement"><codeblock></code> processing, and incremental improvements to Lightweight DITA processing and PDF output</span>.</li><li class="link ulchildlink"><strong><a href="../topics/migrating-to-3.0.html">Migrating to release 3.0</a></strong><br>DITA-OT 3.0 <span class="ph">adds support for Markdown, normalized DITA output, and the alternative authoring formats proposed for Lightweight DITA. The map-first preprocessing approach provides a modern alternative to the default <code class="ph codeph">preprocess</code> operation.</span></li><li class="link ulchildlink"><strong><a href="../topics/migrating-to-2.5.html">Migrating to release 2.5</a></strong><br>In DITA-OT 2.5, several frequently-overridden legacy style settings were removed from the default PDF plug-in. A separate plug-in can be used to restore the original settings.</li><li class="link ulchildlink"><strong><a href="../topics/migrating-to-2.4.html">Migrating to release 2.4</a></strong><br>In DITA-OT 2.4, the <span class="keyword option">HTML5</span> transformation was refactored as an independent plug-in that no longer depends on the <span class="keyword option">XHTML</span> plug-in. </li><li class="link ulchildlink"><strong><a href="../topics/migrating-to-2.3.html">Migrating to release 2.3</a></strong><br>In DITA-OT 2.3, <span class="keyword option">HTML5</span> table processing has been refactored to use HTML5 best practices and improved CSS properties. In PDF output, table heads and key columns no longer include shading, and unused localization variables have been deprecated. The template for generated error messages has been updated to use a single <code class="ph codeph">id</code> variable that contains the entire message ID.</li><li class="link ulchildlink"><strong><a href="../topics/migrating-to-2.2.html">Migrating to release 2.2</a></strong><br>In DITA-OT 2.2, the <span class="keyword option">HTML5</span> transformation was refactored as its own plug-in and separate plug-ins were created for each of the rendering engine-specific PDF transformations. </li><li class="link ulchildlink"><strong><a href="../topics/migrating-to-2.1.html">Migrating to release 2.1</a></strong><br>In DITA-OT 2.1, the <code class="ph codeph">insertVariable</code> template was deprecated for PDF transformations and should be replaced with the <code class="ph codeph">getVariable</code> template. Various <code class="ph codeph">dita.<strong class="ph b">out.</strong>map.*</code> targets have been deprecated in favor of updated <code class="ph codeph">dita.map.*</code> equivalents.</li><li class="link ulchildlink"><strong><a href="../topics/migrating-to-2.0.html">Migrating to release 2.0</a></strong><br>In DITA-OT 2.0, XSLT templates were converted to XSLT 2.0, variable typing was implemented, and some older templates were refactored or removed. In addition, the <span class="keyword cmdname">dita</span> command simplifies distribution of plugins by allowing installation from a URL. </li><li class="link ulchildlink"><strong><a href="../topics/migrating-to-1.8.html">Migrating to release 1.8</a></strong><br>In DITA-OT 1.8, certain stylesheets were moved to plug-in specific folders and various deprecated Ant properties, XSLT stylesheets, parameters and modes were removed from the XHTML, PDF and ODT transformations.</li><li class="link ulchildlink"><strong><a href="../topics/migrating-to-1.7.html">Migrating to release 1.7</a></strong><br>In DITA-OT 1.7, a new preprocessing step implements flagging for HTML-based output formats. PDF processing was corrected with regard to <code class="ph codeph">shortdesc</code> handling, and a new XSLT template mode was introduced for HTML TOC processing. Several stylesheets were moved to plug-in specific folders and deprecated properties and XSLT variables were removed. </li><li class="link ulchildlink"><strong><a href="../topics/migrating-to-1.6.html">Migrating to release 1.6</a></strong><br>In DITA-OT 1.6, various <span class="ph filepath">demo</span> plug-ins were removed along with many deprecated properties, targets, templates and modes. The PDF2 transformation no longer supports the beta version of DITA from IBM, the "bkinfo" demo plug-in, or <span class="ph filepath">layout-masters.xml</span> configuration.</li><li class="link ulchildlink"><strong><a href="../topics/migrating-to-1.5.4.html">Migrating to release 1.5.4</a></strong><br>DITA-OT 1.5.4 adds new extension points to configure behavior based on file extensions, declare print transformation types and add mappings to the PDF configuration catalog file. PDF output supports mirrored page layout and uses new font family definitions. Support for several new languages was added for PDF and XHTML output.</li></ul><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/custom-plugins.html" title="In addition to adding plug-ins from the plug-in registry at dita-ot.org/plugins, you can create custom DITA-OT plug-ins of your own to modify the default output, add new output formats, support new languages, or implement DITA topic specializations.">Creating custom plug-ins</a></div></div><div class="linklist relinfo"><strong>Related information</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="https://www.oxygenxml.com/events/2016/dita-ot_day.html#Upgrading_PDF_plugins_to_DITA_OT_2.x" target="_blank" rel="external noopener" title="There are some significant changes to DITA-OT 2.x that can make upgrading PDF plugins written for earlier versions of the OT a challenge. Having just upgraded several plugins, and released a new edition of "DITA For Print," Leigh will share a few of the major things to look out for.">Gotcha! Upgrading PDF plugins to DITA-OT 2.x</a></li></ul></div></nav></article></main></body></html> |