Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Some initial migration considerations for versions 2.0, 2.1, and 2.2 #77

Merged
merged 4 commits into from
Feb 16, 2016
Merged

Some initial migration considerations for versions 2.0, 2.1, and 2.2 #77

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
4579698
Initial migration info for 2.0
shaneataylor Feb 15, 2016
31f5d18
Initial migration info for 2.1
shaneataylor Jan 30, 2016
77ec79d
Initial migration info for 2.2
shaneataylor Jan 30, 2016
6400e83
Change 2.2.0 to 2.2, 2.1.0 to 2.1 per feedback
shaneataylor Feb 16, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 8 additions & 5 deletions dev_ref/dev_ref.ditamap
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,13 +58,16 @@
<topicref href="plugin-sample.dita"/>
</topicset>
<topicref href="../user-guide/dita2pdf-customization.dita"/>
<topicref href="migration.dita">
<topicref href="migrating-to-1.8.dita"/>
<topicref href="migrating-to-1.7.dita">
<topicref href="migration.dita" locktitle="yes">
<topicref href="migrating-to-2.2.dita"><topicmeta><navtitle>To 2.2</navtitle></topicmeta></topicref>
<topicref href="migrating-to-2.1.dita"><topicmeta><navtitle>To 2.1</navtitle></topicmeta></topicref>
<topicref href="migrating-to-2.0.dita"><topicmeta><navtitle>To 2.0</navtitle></topicmeta></topicref>
<topicref href="migrating-to-1.8.dita"><topicmeta><navtitle>To 1.8</navtitle></topicmeta></topicref>
<topicref href="migrating-to-1.7.dita"><topicmeta><navtitle>To 1.7</navtitle></topicmeta>
<topicref rev="1.7" href="flagging-migration.dita" navtitle="Flagging updates" locktitle="yes"/>
</topicref>
<topicref href="migrating-to-1.6.dita"/>
<topicref href="migrating-to-1.5.4.dita"/>
<topicref href="migrating-to-1.6.dita"><topicmeta><navtitle>To 1.6</navtitle></topicmeta></topicref>
<topicref href="migrating-to-1.5.4.dita"><topicmeta><navtitle>To 1.5.4</navtitle></topicmeta></topicref>
</topicref>
<topicref href="DITA1.2-implementation-dependent-features.dita"/>
<topicref href="extended-functionality.dita"/>
Expand Down
54 changes: 54 additions & 0 deletions dev_ref/migrating-to-2.0.dita
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
<!--This file is part of the DITA Open Toolkit project. See the accompanying LICENSE.md file for applicable licenses.-->
<reference id="migrating-to-2.0">
<title>Migrating to Release 2.0</title>
<shortdesc>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
<cmdname>dita</cmdname> command simplifies distribution of plugins by allowing installation
from a URL.<draft-comment author="staylor">There are likely other changes that should be noted
here. See <xref href="../release-notes/rel2.0.dita"/>
</draft-comment></shortdesc>
<refbody>
<refbodydiv>
<section>
<title>All Transformations — Variable Typing</title>
<p>XSLT stylesheets were converted to XSLT 2.0. With that change, variable types were also
implemented. Plugins that change template variable values will need to make the following
changes:</p>
<ul>
<li>Declare the same types defined in the default templates with <xmlatt>as</xmlatt>.</li>
<li>Ensure that the generated values conform to the declared type.</li>
</ul>
</section>
<example>
<p>For example:</p>
<codeblock>&lt;xsl:variable name="urltest">
&lt;xsl:variable name="urltest" <b>as="xs:boolean"</b>></codeblock>
</example>
<section>
<title>All Transformations — Refactoring</title>
<p>Much of the toolkit code was refactored for release 2.0. Customization changes that were
based on a specific template in a previous version of the toolkit might not work because
the modified template is no longer used. If this is the case, the changes will need to be
reimplemented based on the new XSLT templates.</p>
</section>
</refbodydiv>
<section>
<title>HTML5</title>
<p>A new <option>HTML5</option> transformation type has been added. Customizations that
previously modified the XHTML output to generate valid HTML5 should still work, but basing
your customization on the new transformation type might simplify the customization and
reduce the work required to maintain compatibility with future versions of the toolkit.</p>
<note>The <option>HTML5</option> transformation was refactored with release 2.2. Before
basing your customization on the changes in release 2.0, consider whether you might want to
move to release 2.2 instead. See <xref href="migrating-to-2.2.dita"/>.</note>
</section>
<section>
<title>Plugin Installation and Distribution</title>
<p>Plugins can now be installed or uninstalled from a ZIP archive using the new
<cmdname>dita</cmdname> command. Plugins can also be installed from a referenced URL. See
<xref keyref="dita-command-arguments"/>.</p>
</section>
</refbody>
</reference>
27 changes: 27 additions & 0 deletions dev_ref/migrating-to-2.1.dita
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
<!--This file is part of the DITA Open Toolkit project. See the accompanying LICENSE.md file for applicable licenses.-->
<reference id="migrating-to-2.1">
<title>Migrating to Release 2.1</title>
<shortdesc>In DITA-OT 2.1, the <codeph>insertVariable</codeph> template was deprecated for PDF
transformations.<draft-comment author="staylor">There are likely other changes that should be
noted here. See <xref href="../release-notes/rel2.1.dita"/>
</draft-comment></shortdesc>
<refbody>
<section>
<title>PDF</title>
<p>The following template has been deprecated:</p>
<ul>
<li><codeph>insertVariable</codeph></li>
</ul>
<p>Calls to that template will result in warnings in the build log. To update your plugin,
make the following changes:</p>
<codeblock>&lt;xsl:call-template name="<line-through>insertVariable</line-through><b>getVariable</b>">
&lt;xsl:with-param name="<line-through>theVariableID</line-through><b>id</b>" select="<varname>var-id</varname>"/>
&lt;xsl:with-param name="<line-through>theParameters</line-through><b>params</b>">
<varname>params</varname>
&lt;/xsl:with-param>
&lt;/xsl:call-template></codeblock>
</section>
</refbody>
</reference>
72 changes: 72 additions & 0 deletions dev_ref/migrating-to-2.2.dita
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
<!--This file is part of the DITA Open Toolkit project. See the accompanying LICENSE.md file for applicable licenses.-->
<reference id="migrating-to-2.2">
<title>Migrating to Release 2.2</title>
<shortdesc>In DITA-OT 2.2, the <option>HTML5</option> transformation was refactored as its own
plugin and separate plugins were created for each of the rendering engine-specific PDF
transformations.<draft-comment author="staylor">There are likely other changes that should be
noted here. </draft-comment></shortdesc>
<refbody>
<section>
<title>HTML5</title>
<p>The <option>HTML5</option> transformation introduced in release 2.0 as part of the
<option>XHTML</option> plugin has been moved to a separate <option>HTML5</option> plugin.
Customizations that extended the previous HTML5 output under the <option>XHTML</option>
plugin will probably need to be refactored on the new HTML5 plugin.</p>
</section>
<section>
<title>PDF</title>
<p>Processing specific to Apache FOP, Antenna House Formatter, and RenderX XEP has been
separated into separate plugins for each of those rendering engines. Customizations that
extended this processing might need to extend the new <keyword>org.dita.pdf2.fop</keyword>,
<keyword>org.dita.pdf2.axf</keyword>, or <keyword>org.dita.pdf2.xep</keyword> plugins.</p>
<p>PDF customizations that are not specific to a rendering engine can continue to extend the
<keyword>org.dita.pdf2</keyword> plugin as before.</p>
</section>
<section>
<draft-comment author="staylor">Consider whether some of the folloing might be useful:<ul>
<li>some elements are mapped differently ;see <xref
href="http://www.dita-ot.org/2.1/release-notes/index.html" format="html"
scope="external">http://www.dita-ot.org/2.1/release-notes/index.html</xref></li>
<li/>
<li>The custom<systemoutput>FileUtils</systemoutput> code used to handle input and output
in earlier versions of DITA-OT has been replaced with the <xref
href="http://commons.apache.org/proper/commons-io/" format="html" scope="external"
>Apache Commons IO</xref> utilities library.<ul>
<li><xref href="https://github.com/dita-ot/dita-ot/issues/1803" format="html"
scope="external">1803</xref> Use Commons IO</li>
</ul></li>
<li><p>Support for theargs.odt.img.embed parameter has been removed from OpenDocument
format transformations.</p>The previous default behavior was to embed images as
Base64-encoded text, but editors do not use this as a default. Instead, office packages
such as LibreOffice will convert embedded images into linked images on opening and
saving an ODT file.<ul>
<li><xref href="https://github.com/dita-ot/dita-ot/issues/1832" format="html"
scope="external">1832</xref> Remove support for args.odt.img.embed</li>
</ul></li>
<li><p>Keydef processing has been removed from the XHTML rendering code</p>Keys are now
resolved in one preprocessing step, whereas in earlier versions of DITA-OT, the XHTML
code returned to thekeydef.xml file to look up targets for phrase elements and pull in
text when needed. This change affects non-linking elements that can't take
<systemoutput>@href</systemoutput> attributes, such as
<systemoutput>&lt;ph></systemoutput>, <systemoutput>&lt;keyword></systemoutput>,
<systemoutput>&lt;cite></systemoutput>, <systemoutput>&lt;dt></systemoutput>,
<systemoutput>&lt;term></systemoutput>, and
<systemoutput>&lt;indexterm></systemoutput> (when
<systemoutput>$INDEXSHOW</systemoutput> is active).<ul>
<li><xref href="https://github.com/dita-ot/dita-ot/issues/1837" format="html"
scope="external">1837</xref> Remove keydef processing from XHTML rendering
code</li>
</ul></li>
<li><p>A new<systemoutput>dita.parser</systemoutput> extension point has been added to
allow plug-ins to contribute a custom parser for DITA files.</p>If a custom DITA
parser is defined, the preprocessing routines will use it during the gen-list and
debug-filter stages to output DITA XML.<ul>
<li><xref href="https://github.com/dita-ot/dita-ot/issues/1847" format="html"
scope="external">1847</xref> Extension-point for custom DITA parsers</li>
</ul></li>
</ul></draft-comment>
</section>
</refbody>
</reference>