98 lines
No EOL
12 KiB
HTML
98 lines
No EOL
12 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="DITA-OT 3.0 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 preprocess operation."><meta name="keywords" content="Lightweight DITA, GitHub"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Migrating to release 3.0</title></head><body id="migrating-to-3.0"><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><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 class="active"><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 to release 3.0</h1>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<div class="body refbody"><p class="shortdesc">DITA-OT 3.0 <span class="ph" id="migrating-to-3.0__summary">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></p>
|
||
<section class="section">
|
||
<div class="note note note_note"><span class="note__title">Note:</span> This topic provides a summary of changes in DITA-OT 3.0 that may require modifications to custom stylesheets
|
||
or plug-ins. For more information on changes in this release, see the
|
||
<a class="xref" href="https://www.dita-ot.org/3.0/release-notes/" target="_blank" rel="external noopener">DITA-OT 3.0 Release Notes</a>.</div>
|
||
</section>
|
||
|
||
<section class="section"><h2 class="title sectiontitle">Upgrade stylesheets to XSLT 2.0</h2>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<p class="p">The Saxon project has announced plans to remove XSLT 1.0 support from the Saxon-HE library that ships with
|
||
DITA-OT:</p>
|
||
<blockquote class="lq">…we’re dropping XSLT 1.0
|
||
backwards compatibility mode from Saxon-HE, and hope to eliminate it entirely in due course.<br><div><a href="https://www.xml.com/news/release-saxon-98/"><cite>https://www.xml.com/news/release-saxon-98/</cite></a></div></blockquote>
|
||
<p class="p">DITA-OT 3.0 and 3.0.1 included Saxon-HE 9.8.0.5, which rejects XSLT stylesheets that specify
|
||
<code class="ph codeph">version="1.0"</code>. Plug-ins with XSLT templates specifying version 1.0 will fail with the message
|
||
“<samp class="ph msgph">XSLT 1.0 compatibility mode is not available in this configuration</samp>.”</p>
|
||
<p class="p">To resolve this issue, change any occurrences of <code class="ph codeph"><xsl:stylesheet version="1.0"></code> in custom
|
||
plug-in stylesheets to at least <code class="ph codeph"><xsl:stylesheet version="2.0"></code>.</p>
|
||
<div class="note tip note_tip"><span class="note__title">Tip:</span> DITA-OT 3.0.2 includes Saxon-HE 9.8.0.7, which restores XSLT 1.0 backwards-compatibility mode,
|
||
but the DITA Open Toolkit project recommends upgrading all stylesheets to XSLT 2.0 to ensure plug-ins remain
|
||
compatible with future versions of DITA-OT and Saxon-HE.</div>
|
||
</section>
|
||
|
||
<section class="section" id="migrating-to-3.0__30-legacy-plugin-removal"><h2 class="title sectiontitle">Legacy plug-ins removed</h2>
|
||
|
||
|
||
|
||
|
||
<p class="p">DITA-OT 3.0 no longer includes the following legacy transformation plug-ins in the default distribution:</p>
|
||
<table class="table table-hover frame-none"><caption><span class="table--title-label">Table 1. </span><span class="title">Legacy plug-ins</span></caption><colgroup><col style="width:50%"><col style="width:50%"></colgroup><thead class="thead">
|
||
<tr class="row">
|
||
<th class="entry colsep-0 rowsep-1" id="migrating-to-3.0__30-legacy-plugin-removal__entry__1">Plug-in </th>
|
||
<th class="entry colsep-0 rowsep-1" id="migrating-to-3.0__30-legacy-plugin-removal__entry__2">Source code location</th>
|
||
</tr>
|
||
</thead><tbody class="tbody">
|
||
<tr class="row">
|
||
<td class="entry colsep-0 rowsep-1" headers="migrating-to-3.0__30-legacy-plugin-removal__entry__1">JavaHelp
|
||
</td>
|
||
<td class="entry colsep-0 rowsep-1" headers="migrating-to-3.0__30-legacy-plugin-removal__entry__2">
|
||
<a class="xref" href="https://github.com/dita-ot/org.dita.javahelp" target="_blank" rel="external noopener">https://github.com/dita-ot/org.dita.javahelp</a></td>
|
||
</tr>
|
||
</tbody></table>
|
||
<div class="note note note_note"><span class="note__title">Note:</span> If necessary, legacy plug-ins may be re-installed from earlier DITA-OT
|
||
distributions, but they are no longer actively maintained or supported by the core toolkit committers. The
|
||
source code is available on GitHub for anyone interested in maintaining the plug-ins for use with future toolkit
|
||
versions.</div>
|
||
<p class="p">To re-install the JavaHelp plug-in, run the following command:</p>
|
||
<pre class="pre codeblock"><code><span class="keyword cmdname">dita</span> <span class="keyword parmname">--install</span>=<span class="ph filepath">https://github.com/dita-ot/org.dita.javahelp/archive/2.5.zip</span></code></pre>
|
||
</section>
|
||
|
||
<section class="section" id="migrating-to-3.0__map-first"><h2 class="title sectiontitle">Map-first preprocessing</h2>
|
||
|
||
<p class="p"><span class="ph">DITA-OT 3.0 provides a map-first preprocessing option as an alternative to
|
||
the default <code class="ph codeph">preprocess</code> operation. The method, which was introduced in DITA-OT 2.5 as an
|
||
experimental feature, has been improved and is ready for use in many production scenarios. Map-first-preprocessing
|
||
provides the same functionality as the default <code class="ph codeph">preprocess</code>, but takes a different
|
||
approach.</span></p>
|
||
<p class="p">The internal extension points that run before or after individual steps in the
|
||
original <code class="ph codeph">preprocess</code> pipeline (<code class="ph codeph">preprocess.*.pre/preprocess.*.post</code>) are not
|
||
available in the newer map-first preprocessing pipeline (<code class="ph codeph">preprocess2</code>), which is used in the PDF
|
||
and HTML Help transformations as of DITA-OT 3.0.</p>
|
||
<div class="note tip note_tip"><span class="note__title">Tip:</span> See
|
||
<a class="xref" href="../reference/map-first-preprocessing.html" title="DITA-OT 3.0 provides a map-first preprocessing option as an alternative to the default preprocess operation. The method, which was introduced in DITA-OT 2.5 as an experimental feature, has been improved and is ready for use in many production scenarios. Map-first-preprocessing provides the same functionality as the default preprocess, but takes a different approach.">Map-first preprocessing</a> for information on how to use (or test) map-first preprocessing, or revert to
|
||
the default <code class="ph codeph">preprocess</code> target.</div>
|
||
</section>
|
||
|
||
<section class="section"><h2 class="title sectiontitle">New <code class="ph codeph">ant.import</code> extension point</h2>
|
||
|
||
<p class="p">A new extension point has been added to make it easier to add new targets to the Ant processing pipeline.</p>
|
||
<p class="p">Earlier versions of DITA-OT use the <code class="ph codeph">dita.conductor.target.relative</code> to call a wrapper file with
|
||
a dummy task that imports the Ant project file. This approach is still supported for backwards compatibility,
|
||
but the simpler <code class="ph codeph">ant.import</code> approach should be used for all new customizations. </p>
|
||
<div class="note tip note_tip"><span class="note__title">Tip:</span> See
|
||
<a class="xref" href="plugin-anttarget.html" title="As of DITA-OT 3.0, the ant.import extension point can be used to make new targets available to the Ant processing pipeline. This can be done as part of creating a new transformation, extending pre-processing, or simply to make new Ant targets available to other plug-ins.">Adding a new target to the Ant build process</a> for details.</div>
|
||
</section>
|
||
</div>
|
||
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/migration.html" title="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.">Migrating customizations</a></div></div></nav></article></main></body></html> |