apb/code-srv-test
apb/code-srv-test
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity Actions

from code-server

Browse source
This commit is contained in:
Andy Bunce 2021-03-23 22:38:58 +00:00
parent eda5c02fe9
commit 5ef8bdba47
2652 changed files with 528235 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

15
dita-ot-3.6/doc/topics/adding-plugins.html Normal file
View file

@ -0,0 +1,15 @@
<!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="You can extend DITA-OT with additional plug-ins to change the default output types in various ways, add entirely new kinds of output formats, or implement DITA specializations. A variety of open source plug-ins are available from the plug-in registry at dita-ot.org/plugins."><meta name="keywords" content="DITA, specializations, plug-ins, plug-ins, working with"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Adding and removing plug-ins</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 class="active"><a href="../topics/adding-plugins.html">Adding plug-ins</a><ul><li><a href="../topics/plugins-installing.html">Installing plug-ins</a></li><li><a href="../topics/plugins-removing.html">Removing plug-ins</a></li><li><a href="../topics/plugins-registry.html">Plug-in registry</a></li><li><a href="../topics/rebuilding-docs.html">Rebuilding documentation</a></li></ul></li><li><a href="../topics/custom-plugins.html">Creating plug-ins</a></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">Adding and removing plug-ins</h1>
<div class="body conbody"><p class="shortdesc">You can extend DITA-OT with additional plug-ins to change the default output types in various ways, add
entirely new kinds of output formats, or implement DITA specializations. A variety of open source plug-ins are
available from the plug-in registry at
<a class="xref" href="https://www.dita-ot.org/plugins" target="_blank" rel="external noopener">dita-ot.org/plugins</a>.</p></div>
<nav role="navigation" class="related-links"><ul class="ullinks"><li class="link ulchildlink"><strong><a href="../topics/plugins-installing.html">Installing plug-ins</a></strong><br>Use the <span class="keyword cmdname">dita install</span> subcommand to install plug-ins.</li><li class="link ulchildlink"><strong><a href="../topics/plugins-removing.html">Removing plug-ins</a></strong><br>Use the <span class="keyword cmdname">dita uninstall</span> subcommand to remove a plug-in.</li><li class="link ulchildlink"><strong><a href="../topics/plugins-registry.html">Adding plug-ins via the registry</a></strong><br><span class="ph">DITA-OT 3.2 supports a new plug-in registry that makes it easier to discover and install new plug-ins. The registry provides a searchable list of plug-ins at <a class="xref" href="https://www.dita-ot.org/plugins" target="_blank" rel="external noopener">dita-ot.org/plugins</a>.</span></li><li class="link ulchildlink"><strong><a href="../topics/rebuilding-docs.html">Rebuilding the DITA-OT documentation</a></strong><br>When you add or remove plug-ins, you can rebuild the documentation to update the information on the extension points, messages, and parameters that are available in your environment.</li></ul></nav></article></main></body></html>

18
dita-ot-3.6/doc/topics/ant.html Normal file
View file

@ -0,0 +1,18 @@
<!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="Ant is a Java-based, open-source tool that is provided by the Apache Foundation. It can be used to declare a sequence of build actions. It is well suited for both development and document builds. The toolkit ships with a copy of Ant."><meta name="keywords" content="Ant, overview, build.xml, files, XSLT, Ant, Java"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Ant</title></head><body id="ant"><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><ul><li><a href="../topics/build-using-dita-command.html">Using the dita command</a></li><li><a href="../topics/using-docker-images.html">Using Docker images</a></li><li><a href="../topics/publishing-with-ant.html">Using Ant</a><ul><li class="active"><a href="../topics/ant.html">Ant</a></li><li><a href="../topics/building-with-ant.html">Building output using Ant</a></li><li><a href="../topics/creating-an-ant-build-script.html">Creating an Ant build script</a></li></ul></li><li><a href="../reference/java-api.html">Using the Java API</a></li></ul></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></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">Ant</h1>
<div class="body conbody"><p class="shortdesc">Ant is a Java-based, open-source tool that is provided by the Apache Foundation. It can be used to declare
a sequence of build actions. It is well suited for both development and document builds. The toolkit ships with a
copy of Ant.</p>
<p class="p">DITA-OT uses Ant to manage the XSLT scripts that are used to perform the various transformation; it also uses Ant
to manage intermediate steps that are written in Java. </p>
<p class="p">The most important Ant script is the <span class="ph filepath">build.xml</span> file. This script defines and combines common
pre-processing and output transformation routines; it also defines the DITA-OT extension points.</p>
</div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/publishing-with-ant.html" title="You can use Ant to invoke DITA Open Toolkit and generate output. You can use the complete set of parameters that the toolkit supports.">Building output using Ant</a></div></div><div class="linklist reltasks"><strong>Related tasks</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/migrating-ant-to-dita.html" title="Although DITA Open Toolkit still supports Ant builds, switching to the dita command offers a simpler command interface, sets all required environment variables and allows you to run DITA-OT without setting up anything beforehand.">Migrating Ant builds to use the dita command</a></li><li class="linklist"><a class="link" href="../topics/building-with-ant.html" title="You can build output by using an Ant build script to provide the DITA-OT parameters.">Building output using Ant</a></li><li class="linklist"><a class="link" href="../topics/creating-an-ant-build-script.html" title="Instead of typing the DITA-OT parameters at the command prompt, you might want to create an Ant build script that contains all of the parameters.">Creating an Ant build script</a></li></ul></div><div class="linklist relref"><strong>Related reference</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../parameters/parameters_intro.html" title="Certain parameters apply to all DITA-OT transformations. Other parameters are common to the HTML-based transformations. Some parameters apply only to specific transformation types. These parameters can be passed as options to the dita command using the --parameter=value syntax or included in build scripts as Ant properties.">DITA-OT parameters</a></li><li class="linklist"><a class="link" href="http://ant.apache.org/manual" target="_blank" rel="external noopener">Apache Ant documentation</a></li></ul></div></nav></article></main></body></html>

243
dita-ot-3.6/doc/topics/build-using-dita-command.html Normal file
View file

@ -0,0 +1,243 @@
<!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="You can generate output using the dita command-line tool. Build parameters can be specified on the command line or with .properties files."><meta name="keywords" content="macOS, command, dita, Linux, Windows, command, using"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Building output using the dita command</title></head><body id="using-command-line-tool"><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><ul><li class="active"><a href="../topics/build-using-dita-command.html">Using the dita command</a><ul><li><a href="../topics/using-dita-properties-file.html">Using a properties file</a></li><li><a href="../topics/migrating-ant-to-dita.html">Migrating Ant builds</a></li><li><a href="../topics/using-project-files.html">Using a project file</a></li></ul></li><li><a href="../topics/using-docker-images.html">Using Docker images</a></li><li><a href="../topics/publishing-with-ant.html">Using Ant</a></li><li><a href="../reference/java-api.html">Using the Java API</a></li></ul></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></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">Building output using the <span class="keyword cmdname">dita</span> command</h1>
<div class="body taskbody"><p class="shortdesc">You can generate output using the <span class="keyword cmdname">dita</span> command-line tool. Build parameters can be
specified on the command line or with <span class="ph filepath">.properties</span> files.</p>
<section><div class="tasklabel"><h2 class="sectiontitle tasklabel">Procedure</h2></div><div class="ol steps"><div class="li step p">
<span class="ph cmd">At the command-line prompt, enter the following command:</span>
<div class="itemgroup info"><pre class="pre codeblock syntax-bash"><code><span class="ph filepath"><span class="keyword cmdname">dita</span></span> <span class="keyword parmname">--input</span>=<var class="keyword varname">input-file</var> <span class="keyword parmname">--format</span>=<var class="keyword varname">format</var> <span class="ph">[<var class="keyword varname">options</var>]</span></code></pre>
<p class="p">where:</p>
<ul class="ul">
<li class="li"><var class="keyword varname">input-file</var> is the DITA map or DITA file that you want to
process.</li>
<li class="li">
<p class="p">
<var class="keyword varname">format</var> is the output format (transformation type). This argument corresponds to the
common parameter <span class="keyword parmname">transtype</span>. Use the same values as for the
<span class="keyword parmname">transtype</span> build parameter, for example <span class="keyword option">html5</span> or
<span class="keyword option">pdf</span>.</p>
<div class="p" id="using-command-line-tool__d1183e290">You can create plug-ins to add new output formats; by default, the following values are
available:
<ul class="ul">
<li class="li"><span class="keyword option">dita</span></li>
<li class="li"><span class="keyword option">eclipsehelp</span></li>
<li class="li"><span class="keyword option">html5</span></li>
<li class="li"><span class="keyword option">htmlhelp</span></li>
<li class="li"><span class="keyword option">markdown</span>, <span class="keyword option">markdown_gitbook</span>, and
<span class="keyword option">markdown_github</span></li>
<li class="li"><span class="keyword option">pdf</span></li>
<li class="li"><span class="keyword option">xhtml</span></li>
</ul>
<div class="note tip note_tip"><span class="note__title">Tip:</span> See
<a class="xref" href="output-formats.html" title="DITA Open Toolkit ships with several core transformations that convert DITA content to different output formats. Additional formats are available from the plug-in registry at dita-ot.org/plugins.">DITA-OT transformations (output formats)</a> for sample command line syntax and more information on each
transformation. </div>
</div>
</li>
<li class="li">[<var class="keyword varname">options</var>] include the following optional build parameters:
<dl class="dl parml">
<dt class="dt pt dlterm">
<span class="keyword parmname">--debug</span></dt>
<dt class="dt pt dlterm">
<span class="keyword parmname">-d</span>
</dt>
<dd class="dd pd">Debug logging prints considerably more additional information. The debug log includes all information from
the verbose log, plus details on Java classes, additional Ant properties and overrides, preprocessing
filters, parameters, and stages, and the complete build sequence. Debug logging requires additional
resources and can slow down the build process, so it should only be enabled when further details are
required to diagnose problems.</dd>
<dt class="dt pt dlterm">
<span class="keyword parmname">--output</span>=<var class="keyword varname">dir</var></dt>
<dt class="dt pt dlterm">
<span class="keyword parmname">-o</span>
<var class="keyword varname">dir</var>
</dt>
<dd class="dd pd" id="using-command-line-tool__d1183e385">
<p class="p">Specifies the path of the output directory; the path can be absolute or relative to the current
directory.</p>
<p class="p">This argument corresponds to the common parameter <span class="keyword parmname">output.dir</span>. By default, the output
is written to the <span class="ph filepath">out</span> subdirectory of the current directory.</p>
</dd>
<dt class="dt pt dlterm">
<span class="keyword parmname">--filter</span>=<var class="keyword varname">files</var>
</dt>
<dd class="dd pd">
<p class="p">Specifies filter file(s) used to include, exclude, or flag content. Relative paths are resolved against
the current directory and internally converted to absolute paths.</p>
<div class="note note note_note"><span class="note__title">Note:</span>
<p class="p">To specify multiple filter files, use the system path separator character to delimit individual file
paths (semicolon ‘<code class="ph codeph">;</code>’ on Windows, and colon ‘<code class="ph codeph">:</code>’ on macOS and Linux) and
wrap the value in quotes:</p>
<p class="p"><code class="ph codeph">--filter="filter1.ditaval;filter2.ditaval;filter3.ditaval"</code></p>
<p class="p">As of DITA-OT 3.6, the <span class="keyword parmname">--filter</span> option can also be passed multiple times:</p>
<p class="p"><code class="ph codeph">--filter=filter1.ditaval --filter=filter2.ditaval --filter=filter3.ditaval</code></p>
<p class="p">DITAVAL files are evaluated in the order specified, so conditions specified in the first file take
precedence over matching conditions specified in later files, just as conditions at the start of a
DITAVAL document take precedence over matching conditions later in the same document.</p>
</div>
</dd>
<dt class="dt pt dlterm">
<span class="keyword parmname">--force</span>
</dt>
<dd class="dd pd">Force-install an existing plug-in.</dd>
<dd class="dd pd ddexpand">Passed as an additional option to the installation subcommand: <span class="keyword cmdname">dita
install</span>&nbsp;<var class="keyword varname">plug-in-zip</var>&nbsp;<span class="keyword parmname">--force</span></dd>
<dt class="dt pt dlterm">
<span class="keyword parmname">--help</span></dt>
<dt class="dt pt dlterm">
<span class="keyword parmname">-h</span>
</dt>
<dd class="dd pd">Print a list of available arguments, options, and subcommands.</dd>
<dt class="dt pt dlterm">
<span class="keyword parmname">--logfile</span>=<var class="keyword varname">file</var></dt>
<dt class="dt pt dlterm">
<span class="keyword parmname">-l</span>
<var class="keyword varname">file</var>
</dt>
<dd class="dd pd">Write logging messages to a file.</dd>
<dt class="dt pt dlterm">
<span class="keyword parmname">--parameter</span>=<var class="keyword varname">value</var></dt>
<dt class="dt pt dlterm">
<span class="keyword parmname">-D</span><var class="keyword varname">parameter</var>=<var class="keyword varname">value</var>
</dt>
<dd class="dd pd">Specify a value for a DITA-OT or Ant build parameter.</dd>
<dd class="dd pd ddexpand">The GNU-style <span class="keyword parmname">--parameter</span>=<var class="keyword varname">value</var> form is only available for
parameters that are configured in the plug-in configuration file; the Java-style <span class="keyword parmname">-D</span>
form can also be used to specify additional non-configured parameters or set system properties.</dd>
<dd class="dd pd ddexpand">Parameters not implemented by the specified transformation type or referenced in a
<span class="ph filepath">.properties</span> file are ignored. <div class="note tip note_tip"><span class="note__title">Tip:</span> If you are building in different environments where the location of the input
files is not consistent, set <span class="keyword option">args.input.dir</span> with the <span class="keyword cmdname">dita</span> command and
reference its value with <code class="ph codeph">${args.input.dir}</code> in your <span class="ph filepath">.properties</span> file.
</div>
</dd>
<dt class="dt pt dlterm">
<span class="keyword parmname">--propertyfile</span>=<var class="keyword varname">file</var>
</dt>
<dd class="dd pd">Use build parameters defined in the referenced <span class="ph filepath">.properties</span> file.</dd>
<dd class="dd pd ddexpand">Build parameters specified on the command line override those set in the <span class="ph filepath">.properties</span>
file.</dd>
<dt class="dt pt dlterm">
<span class="keyword parmname">--repeat</span>=<var class="keyword varname">N</var>
</dt>
<dd class="dd pd">Repeat the transformation <var class="keyword varname">N</var> number of times.</dd>
<dd class="dd pd ddexpand">This option can be used by plug-in developers to measure performance. To run a conversion five times, for
example, use <span class="keyword parmname">--repeat</span>=<span class="keyword option">5</span>. The duration of each execution will appear in
the console when the final transformation is complete.
<pre class="pre codeblock syntax-bash multi-platform"><code>$ <span class="keyword cmdname">dita</span> <span class="keyword parmname">--input</span>=<span class="ph filepath">docsrc/samples/sequence.ditamap</span> <span class="keyword parmname">--format</span>=<span class="keyword option">html5</span> <span class="keyword parmname">--repeat</span>=<span class="keyword option">5</span>
1 11281ms
2 4132ms
3 3690ms
4 4337ms
5 3634ms</code></pre>
</dd>
<dt class="dt pt dlterm">
<span class="keyword parmname">--resource</span>=<var class="keyword varname">file</var>
</dt>
<dt class="dt pt dlterm">
<span class="keyword parmname">-r</span>
<var class="keyword varname">file</var>
</dt>
<dd class="dd pd">Convert partial documentation sets by processing input with additional resources.</dd>
<dd class="dd pd ddexpand">For example, to process a single topic file with a map that contains key definitions, use a command like
this:
<pre class="pre codeblock syntax-bash"><code><span class="keyword cmdname">dita</span> <span class="keyword parmname">--input</span>=<span class="ph filepath">topic.dita</span> <span class="keyword parmname">--resource</span>=<span class="ph filepath">keys.ditamap</span> <span class="keyword parmname">--format</span>=<span class="keyword option">html5</span></code></pre>
</dd>
<dd class="dd pd ddexpand">To convert a chapter map to HTML5 and insert related links from relationship tables in a separate map,
use:
<pre class="pre codeblock syntax-bash"><code><span class="keyword cmdname">dita</span> <span class="keyword parmname">--input</span>=<span class="ph filepath">chapter.ditamap</span> <span class="keyword parmname">--resource</span>=<span class="ph filepath">reltables.ditamap</span> <span class="keyword parmname">--format</span>=<span class="keyword option">html5</span></code></pre>
</dd>
<dt class="dt pt dlterm">
<span class="keyword parmname">--temp</span>=<var class="keyword varname">dir</var></dt>
<dt class="dt pt dlterm">
<span class="keyword parmname">-t</span>
<var class="keyword varname">dir</var>
</dt>
<dd class="dd pd">Specifies the location of the temporary directory.</dd>
<dd class="dd pd ddexpand">This argument corresponds to the common parameter <span class="keyword parmname">dita.temp.dir</span>.</dd>
<dt class="dt pt dlterm">
<span class="keyword parmname">--verbose</span></dt>
<dt class="dt pt dlterm">
<span class="keyword parmname">-v</span>
</dt>
<dd class="dd pd">Verbose logging prints additional information to the console, including directory settings, effective
values for Ant properties, input/output files, and informational messages to assist in troubleshooting.</dd>
</dl></li>
</ul></div>
<div class="itemgroup stepresult">
<p class="p">If processing is successful, nothing is printed in the terminal window. The built output is written to the
specified output directory (by default, in the <span class="ph filepath">out</span> subdirectory of the current
directory).</p>
</div>
</div></div></section>
<section class="example"><div class="tasklabel"><h2 class="sectiontitle tasklabel">Example</h2></div>
<p class="p">For example, from <span class="ph filepath"><var class="keyword varname">dita-ot-dir</var>/docsrc/samples</span>, run:</p>
<div class="p">
<pre class="pre codeblock syntax-bash multi-platform"><code><span class="keyword cmdname">dita</span> <span class="keyword parmname">--input</span>=<span class="ph filepath">sequence.ditamap</span> <span class="keyword parmname">--format</span>=<span class="keyword option">html5</span> \
<span class="keyword parmname">--output</span>=<span class="ph filepath">output/sequence</span> \
<span class="keyword parmname">--args.input.dir</span>=<span class="ph filepath"><var class="keyword varname">/absolute/path/to/dita-ot-dir</var>/docsrc/samples</span> \
<span class="keyword parmname">--propertyfile</span>=<span class="ph filepath">properties/sequence-html5.properties</span></code></pre>
</div>
<p class="p">This builds <span class="ph filepath">sequence.ditamap</span> to HTML5 output in <span class="ph filepath">output/sequence</span> using
the following additional parameters specified in the <span class="ph filepath">properties/sequence-html5.properties</span>
file:</p>
<div class="p">
<pre class="pre codeblock language-properties normalize-space show-line-numbers show-whitespace"><code># Directory that contains the custom .css file:
args.cssroot = ${args.input.dir}/css/
# Custom .css file used to style output:
args.css = style.css
# Copy the custom .css file to the output directory:
args.copycss = yes
# Location of the copied .css file relative to the output:
args.csspath = branding
# Generate a full navigation TOC in topic pages:
nav-toc = full</code></pre>
</div>
</section>
<section class="section postreq"><div class="tasklabel"><h2 class="sectiontitle tasklabel">What to do next</h2></div>
<p class="p">Usually, you will want to specify a set of reusable build parameters in a
<span class="ph filepath">.properties</span> file.</p>
</section>
</div>
<nav role="navigation" class="related-links"><ul class="ullinks"><li class="link ulchildlink"><strong><a href="../topics/using-dita-properties-file.html">Setting build parameters with .properties files</a></strong><br>Usually, DITA builds require setting a number of parameters that do not change frequently. You can reference a set of build parameters defined in a <span class="ph filepath">.properties</span> file when building output with the <span class="keyword cmdname">dita</span> command. If needed, you can override any parameter by specifying it explicitly as an argument to the <span class="keyword cmdname">dita</span> command.</li><li class="link ulchildlink"><strong><a href="../topics/migrating-ant-to-dita.html">Migrating Ant builds to use the dita command</a></strong><br>Although DITA Open Toolkit still supports Ant builds, switching to the <span class="keyword cmdname">dita</span> command offers a simpler command interface, sets all required environment variables and allows you to run DITA-OT without setting up anything beforehand.</li><li class="link ulchildlink"><strong><a href="../topics/using-project-files.html">Publishing with project files</a></strong><br><span class="ph">DITA-OT 3.4 introduces new project files to define publication projects with multiple deliverables. Projects specify a context, output folder, and publication for each deliverable. A re-usable context groups source files and filters, and a publication defines an output format with transformation parameters. You can pass a project file to the <span class="keyword cmdname">dita</span> command to publish multiple deliverables at once.</span></li></ul><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/building-output.html" title="You can use the dita command-line tool, Ant, or the Java API to transform DITA content to the various output formats that DITA Open Toolkit supports.">Building output</a></div></div><div class="linklist reltasks"><strong>Related tasks</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/dita-command-help.html" title="You can access a list of subcommands and supported parameters for the dita command by passing the --help option on the command line.">Accessing help for the dita command</a></li></ul></div><div class="linklist relref"><strong>Related reference</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../parameters/dita-command-arguments.html" title="The dita command takes mandatory arguments to process DITA content. Subcommands can be used to manage plug-ins, or print information about the current configuration. A series of options are available to modify the command behavior or specify additional configuration parameters.">Arguments and options for the dita command</a></li><li class="linklist"><a class="link" href="../parameters/parameters_intro.html" title="Certain parameters apply to all DITA-OT transformations. Other parameters are common to the HTML-based transformations. Some parameters apply only to specific transformation types. These parameters can be passed as options to the dita command using the --parameter=value syntax or included in build scripts as Ant properties.">DITA-OT parameters</a></li><li class="linklist"><a class="link" href="../parameters/internal-ant-properties.html" title="Reference list of Ant properties used by DITA-OT internally.">Internal Ant properties</a></li></ul></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/2015/dita-ot_day.html#Why_startcmd_is_not_your_friend" target="_blank" rel="external noopener" title="The startcmd batch script made it possible for many to easily use DITA-OT, but whether you realize it or not, it's no longer really necessary. I'll briefly explain where it came from, why it was always more of a kludge than a Feature, and how better DITA-OT designs mean it's no longer needed.">Why "startcmd" is not your friend</a></li></ul></div></nav></article></main></body></html>

10
dita-ot-3.6/doc/topics/building-output.html Normal file
View file

@ -0,0 +1,10 @@
<!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="You can use the dita command-line tool, Ant, or the Java API to transform DITA content to the various output formats that DITA Open Toolkit supports."><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Building output</title></head><body id="tranforming-dita-content"><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 class="active"><a href="../topics/building-output.html">Building output</a><ul><li><a href="../topics/build-using-dita-command.html">Using the dita command</a></li><li><a href="../topics/using-docker-images.html">Using Docker images</a></li><li><a href="../topics/publishing-with-ant.html">Using Ant</a></li><li><a href="../reference/java-api.html">Using the Java API</a></li></ul></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></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">Building output</h1>
<p class="shortdesc">You can use the <span class="keyword cmdname">dita</span> command-line tool, Ant, or the Java API to transform DITA content
to the various output formats that DITA Open Toolkit supports.</p>
<nav role="navigation" class="related-links"><ul class="ullinks"><li class="link ulchildlink"><strong><a href="../topics/build-using-dita-command.html">Building output using the dita command</a></strong><br>You can generate output using the <span class="keyword cmdname">dita</span> command-line tool. Build parameters can be specified on the command line or with <span class="ph filepath">.properties</span> files.</li><li class="link ulchildlink"><strong><a href="../topics/using-docker-images.html">Running the dita command from a Docker image</a></strong><br> <span class="ph"> <a class="xref" href="https://www.docker.com" target="_blank" rel="external noopener">Docker</a> is a platform used to build, share, and run portable application containers. As of version 3.4, the DITA-OT project provides an official Docker container image that includes everything you need to run the toolkit and publish DITA content from a containerized environment.</span></li><li class="link ulchildlink"><strong><a href="../topics/publishing-with-ant.html">Building output using Ant</a></strong><br>You can use Ant to invoke DITA Open Toolkit and generate output. You can use the complete set of parameters that the toolkit supports.</li><li class="link ulchildlink"><strong><a href="../reference/java-api.html">Using the Java API</a></strong><br>DITA Open Toolkit includes a Java Application Programming Interface to allow developers to embed the toolkit more easily into other Java programs.</li></ul><div class="linklist relinfo"><strong>Related information</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="https://www.oxygenxml.com/events/2015/dita-ot_day.html#How_To_Run_DITA_OT" target="_blank" rel="external noopener" title="There are multiples ways to run DITA-OT and some of them are good, some are bad, and some are just plain ugly. This presentation goes through different interfaces to DITA-OT and when to use them.">How to run DITA-OT</a></li></ul></div></nav></article></main></body></html>

43
dita-ot-3.6/doc/topics/building-with-ant.html Normal file
View file

@ -0,0 +1,43 @@
<!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="You can build output by using an Ant build script to provide the DITA-OT parameters."><meta name="keywords" content=", default, macOS, Ant, Linux, Windows, Ant, publishing with"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Building output using Ant</title></head><body id="runant"><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><ul><li><a href="../topics/build-using-dita-command.html">Using the dita command</a></li><li><a href="../topics/using-docker-images.html">Using Docker images</a></li><li><a href="../topics/publishing-with-ant.html">Using Ant</a><ul><li><a href="../topics/ant.html">Ant</a></li><li class="active"><a href="../topics/building-with-ant.html">Building output using Ant</a></li><li><a href="../topics/creating-an-ant-build-script.html">Creating an Ant build script</a></li></ul></li><li><a href="../reference/java-api.html">Using the Java API</a></li></ul></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></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">Building output using Ant</h1>
<div class="body taskbody"><p class="shortdesc">You can build output by using an Ant build script to provide the DITA-OT parameters.</p>
<section><div class="tasklabel"><h2 class="sectiontitle tasklabel">Procedure</h2></div><ol class="ol steps"><li class="li step stepexpand">
<span class="ph cmd">Open a command prompt or terminal session.</span>
</li><li class="li step stepexpand">
<span class="ph cmd">Issue the following command:</span>
<table border="1" frame="hsides" rules="rows" cellpadding="4" cellspacing="0" summary="" class="simpletable choicetable choicetableborder multi-platform"><colgroup><col style="width:25%"><col style="width:75%"></colgroup><thead><tr class="sthead chhead"><th scope="col" class="stentry choptionhd" style="vertical-align:bottom;text-align:left;">Option</th><th scope="col" class="stentry chdeschd" style="vertical-align:bottom;text-align:left;">Description</th></tr></thead><tbody><tr class="strow chrow">
<th style="vertical-align:top;" scope="row" class="stentry choption">Linux or macOS&nbsp;</th>
<td style="vertical-align:top;" class="stentry chdesc">
<span class="keyword cmdname">bin/ant</span>
<span class="keyword option">-f</span>
<code class="ph codeph"><var class="keyword varname">build-script</var>
<var class="keyword varname">target</var></code>
</td>
</tr><tr class="strow chrow">
<th style="vertical-align:top;" scope="row" class="stentry choption">Windows</th>
<td style="vertical-align:top;" class="stentry chdesc">
<span class="keyword cmdname">bin\ant</span>
<span class="keyword option">-f</span>
<code class="ph codeph"><var class="keyword varname">build-script</var>
<var class="keyword varname">target</var></code>
</td>
</tr></tbody></table>
<div class="itemgroup info"> where:
<ul class="ul">
<li class="li"><var class="keyword varname">build-script</var> is name of the Ant build script.</li>
<li class="li"><var class="keyword varname">target</var> is an optional switch that specifies the name of the Ant target that you want
to run.
<p class="p">If you do not specify a target, the value of the <code class="keyword markupname xmlatt">@default</code> attribute for the Ant project
is used.</p>
</li>
</ul></div>
</li></ol></section>
</div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/publishing-with-ant.html" title="You can use Ant to invoke DITA Open Toolkit and generate output. You can use the complete set of parameters that the toolkit supports.">Building output using Ant</a></div></div><div class="linklist relconcepts"><strong>Related concepts</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/ant.html" title="Ant is a Java-based, open-source tool that is provided by the Apache Foundation. It can be used to declare a sequence of build actions. It is well suited for both development and document builds. The toolkit ships with a copy of Ant.">Ant</a></li></ul></div><div class="linklist reltasks"><strong>Related tasks</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/creating-an-ant-build-script.html" title="Instead of typing the DITA-OT parameters at the command prompt, you might want to create an Ant build script that contains all of the parameters.">Creating an Ant build script</a></li><li class="linklist"><a class="link" href="../topics/migrating-ant-to-dita.html" title="Although DITA Open Toolkit still supports Ant builds, switching to the dita command offers a simpler command interface, sets all required environment variables and allows you to run DITA-OT without setting up anything beforehand.">Migrating Ant builds to use the dita command</a></li></ul></div><div class="linklist relref"><strong>Related reference</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../parameters/parameters_intro.html" title="Certain parameters apply to all DITA-OT transformations. Other parameters are common to the HTML-based transformations. Some parameters apply only to specific transformation types. These parameters can be passed as options to the dita command using the --parameter=value syntax or included in build scripts as Ant properties.">DITA-OT parameters</a></li><li class="linklist"><a class="link" href="http://ant.apache.org/manual" target="_blank" rel="external noopener">Apache Ant documentation</a></li></ul></div></nav></article></main></body></html>

105
dita-ot-3.6/doc/topics/creating-an-ant-build-script.html Normal file
View file

@ -0,0 +1,105 @@
<!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="Instead of typing the DITA-OT parameters at the command prompt, you might want to create an Ant build script that contains all of the parameters."><meta name="keywords" content=", link, name, default, Ant, build script, relationship tables, PDF"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Creating an Ant build script</title></head><body id="creating-an-ant-build-script"><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><ul><li><a href="../topics/build-using-dita-command.html">Using the dita command</a></li><li><a href="../topics/using-docker-images.html">Using Docker images</a></li><li><a href="../topics/publishing-with-ant.html">Using Ant</a><ul><li><a href="../topics/ant.html">Ant</a></li><li><a href="../topics/building-with-ant.html">Building output using Ant</a></li><li class="active"><a href="../topics/creating-an-ant-build-script.html">Creating an Ant build script</a></li></ul></li><li><a href="../reference/java-api.html">Using the Java API</a></li></ul></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></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">Creating an Ant build script</h1>
<div class="body taskbody"><p class="shortdesc">Instead of typing the DITA-OT parameters at the command prompt, you might want to create an Ant build
script that contains all of the parameters.</p>
<section><div class="tasklabel"><h2 class="sectiontitle tasklabel">Procedure</h2></div><ol class="ol steps"><li class="li step stepexpand">
<span class="ph cmd">Create an XML file that contains the following content:</span>
<div class="itemgroup info">
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;?xml version="1.0" encoding="UTF-8" ?&gt;
&lt;project name="%project-name%" default="%default-target%" basedir="."&gt;
&lt;property name="dita.dir" location="%path-to-DITA-OT%"/&gt;
&lt;target name="%target-name%"&gt;
&lt;ant antfile="${dita.dir}/build.xml"&gt;
&lt;property name="args.input" value="%DITA-input%"/&gt;
&lt;property name="transtype" value="html5"/&gt;
&lt;/ant&gt;
&lt;/target&gt;
&lt;/project&gt;</code></pre>
</div>
<div class="itemgroup info">You will replace the placeholder content (indicated by the % signs) with content applicable to your
environment.</div>
</li><li class="li step stepexpand">
<span class="ph cmd">Specify project information:</span>
<ol type="a" class="ol substeps">
<li class="li substep substepexpand"><strong>Optional: </strong>
<span class="ph cmd">Set the value of the <code class="keyword markupname xmlatt">@name</code> attribute to the name of your project.</span>
</li>
<li class="li substep substepexpand">
<span class="ph cmd">Set the value of the <code class="keyword markupname xmlatt">@default</code> attribute to the name of a target in the build
script.</span>
<div class="itemgroup info">If the build script is invoked without specifying a target, this target will be run.</div>
</li>
</ol>
</li><li class="li step stepexpand">
<span class="ph cmd">Set the value of the <span class="keyword parmname">dita.dir</span> property to the location of the DITA-OT
installation.</span>
<div class="itemgroup info">This can be a fully qualified path, or you can specify it relative to the location of the Ant build script
that you are writing. </div>
</li><li class="li step stepexpand">
<span class="ph cmd">Create the Ant target:</span>
<ol type="a" class="ol substeps">
<li class="li substep">
<span class="ph cmd">Set the value of the <code class="keyword markupname xmlatt">@name</code> attribute.</span>
</li>
<li class="li substep">
<span class="ph cmd">Specify the value for the <span class="keyword parmname">args.input</span> property.</span>
</li>
<li class="li substep">
<span class="ph cmd">Specify the value of the <span class="keyword parmname">transtype</span> property.</span>
</li>
</ol>
</li><li class="li step stepexpand">
<span class="ph cmd">Save the build script.</span>
</li></ol></section>
<section class="example"><div class="tasklabel"><h2 class="sectiontitle tasklabel">Example</h2></div>
<p class="p">The following Ant build script generates CHM and PDF output for the sample DITA maps.</p>
<div class="p">
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;project name="build-chm-pdf" default="all" basedir="."&gt;
&lt;property name="dita.dir" location="${basedir}/../../.."/&gt;
&lt;target name="all" description="build CHM and PDF" depends="chm,pdf"/&gt;
&lt;target name="chm" description="build CHM"&gt;
&lt;ant antfile="${dita.dir}/build.xml"&gt;
&lt;property name="args.input" location="../sequence.ditamap"/&gt;
&lt;property name="transtype" value="htmlhelp"/&gt;
&lt;property name="output.dir" location="../out/chm"/&gt;
&lt;property name="args.gen.task.lbl" value="YES"/&gt;
&lt;/ant&gt;
&lt;/target&gt;
&lt;target name="pdf" description="build PDF"&gt;
&lt;ant antfile="${dita.dir}/build.xml"&gt;
&lt;property name="args.input" location="../taskbook.ditamap"/&gt;
&lt;property name="transtype" value="pdf"/&gt;
&lt;property name="output.dir" location="../out/pdf"/&gt;
&lt;property name="args.gen.task.lbl" value="YES"/&gt;
&lt;property name="args.rellinks" value="nofamily"/&gt;
&lt;/ant&gt;
&lt;/target&gt;
&lt;/project&gt;</code></pre></div>
<div class="p">In addition to the mandatory parameters (<span class="keyword parmname">args.input</span> and <span class="keyword parmname">transtype</span>),
the chm and pdf targets each specify some optional parameters:
<ul class="ul">
<li class="li">The <span class="keyword parmname">args.gen.task.lbl</span> property is set to YES, which ensures that headings are
automatically generated for the sections of task topics.</li>
<li class="li">The <span class="keyword parmname">output.dir</span> property specifies where DITA-OT writes the output of the
transformations.</li>
</ul></div>
<p class="p">The pdf target also specifies that related links should be generated in the PDF, but only those links that are
created by relationship tables and <code class="keyword markupname xmlelement">&lt;link&gt;</code> elements.</p>
<p class="p">Finally, the all target simply specifies that both the chm and pdf target should be run.</p>
</section>
<section class="section postreq"><div class="tasklabel"><h2 class="sectiontitle tasklabel">What to do next</h2></div>Another resource for learning about Ant scripts are the files in the <span class="ph filepath"><var class="keyword varname">dita-ot-dir</var>/docsrc/samples</span><span class="ph filepath">/ant_sample/</span> directory. This
directory contains sample Ant build files for common output formats, as well as templates that you can use to
create your own Ant scripts.</section>
</div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/publishing-with-ant.html" title="You can use Ant to invoke DITA Open Toolkit and generate output. You can use the complete set of parameters that the toolkit supports.">Building output using Ant</a></div></div><div class="linklist relconcepts"><strong>Related concepts</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/ant.html" title="Ant is a Java-based, open-source tool that is provided by the Apache Foundation. It can be used to declare a sequence of build actions. It is well suited for both development and document builds. The toolkit ships with a copy of Ant.">Ant</a></li></ul></div><div class="linklist reltasks"><strong>Related tasks</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/building-with-ant.html" title="You can build output by using an Ant build script to provide the DITA-OT parameters.">Building output using Ant</a></li><li class="linklist"><a class="link" href="../topics/migrating-ant-to-dita.html" title="Although DITA Open Toolkit still supports Ant builds, switching to the dita command offers a simpler command interface, sets all required environment variables and allows you to run DITA-OT without setting up anything beforehand.">Migrating Ant builds to use the dita command</a></li></ul></div><div class="linklist relref"><strong>Related reference</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../parameters/parameters_intro.html" title="Certain parameters apply to all DITA-OT transformations. Other parameters are common to the HTML-based transformations. Some parameters apply only to specific transformation types. These parameters can be passed as options to the dita command using the --parameter=value syntax or included in build scripts as Ant properties.">DITA-OT parameters</a></li><li class="linklist"><a class="link" href="http://ant.apache.org/manual" target="_blank" rel="external noopener">Apache Ant documentation</a></li></ul></div></nav></article></main></body></html>

100
dita-ot-3.6/doc/topics/creating-docker-images.html Normal file
View file

@ -0,0 +1,100 @@
<!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="To install custom plug-ins or make other changes based on the DITA-OT parent image, you can create your own Dockerfile and specify the official DITA-OT image as the basis for your image."><meta name="keywords" content="plug-ins, installing in Docker images, Docker images"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Installing plug-ins in a Docker image</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><ul><li><a href="../topics/build-using-dita-command.html">Using the dita command</a></li><li><a href="../topics/using-docker-images.html">Using Docker images</a><ul><li class="active"><a href="../topics/creating-docker-images.html">Custom images</a></li></ul></li><li><a href="../topics/publishing-with-ant.html">Using Ant</a></li><li><a href="../reference/java-api.html">Using the Java API</a></li></ul></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></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">Installing plug-ins in a Docker image</h1>
<div class="body taskbody"><p class="shortdesc">To install custom plug-ins or make other changes based on the DITA-OT parent image, you can create your own
<span class="ph filepath">Dockerfile</span> and specify the official DITA-OT image as the basis for your image. </p>
<section class="section context"><div class="tasklabel"><h2 class="sectiontitle tasklabel">About this task</h2></div>
<p class="p">Each subsequent declaration in the Dockerfile modifies this parent image, so you can start with the official
image, and add custom plug-ins or other commands as required to create a custom Docker image that includes
everything you need to publish your content.</p></section>
<section><div class="tasklabel"><h2 class="sectiontitle tasklabel">Procedure</h2></div><ol class="ol steps"><li class="li step stepexpand">
<span class="ph cmd">Create a new <span class="ph filepath">Dockerfile</span> and specify the official DITA-OT image in the
<span class="ph filepath">FROM</span> directive.</span>
<div class="itemgroup stepxmp">
<pre class="pre codeblock language-dockerfile normalize-space show-line-numbers show-whitespace"><code># Use the latest official DITA-OT image as parent: ↓
FROM docker.pkg.github.com/dita-ot/dita-ot/dita-ot:3.6</code></pre>
</div>
</li><li class="li step stepexpand"><strong>Optional: </strong>
<span class="ph cmd">You can extend your image with a <code class="ph codeph">RUN</code> declaration that runs the <span class="keyword cmdname">dita</span>
command from the container to install a custom plug-in, and specify the filename or URL of the plug-in’s
distribution ZIP file.</span>
<div class="itemgroup stepxmp">
<pre class="pre codeblock language-dockerfile normalize-space show-line-numbers show-whitespace"><code># Install a custom plug-in from a remote location:
RUN dita --install https://github.com/infotexture/dita-bootstrap/archive/3.4.1.zip</code></pre>
</div>
</li><li class="li step stepexpand"><strong>Optional: </strong>
<span class="ph cmd">You can also install custom plug-ins from the main DITA-OT plug-in registry at
<a class="xref" href="https://www.dita-ot.org/plugins" target="_blank" rel="external noopener">dita-ot.org/plugins</a>, or from your company plug-in registry.</span>
<div class="itemgroup stepxmp">
<pre class="pre codeblock language-dockerfile normalize-space show-line-numbers show-whitespace"><code># Install from the registry at dita-ot.org/plugins:
RUN dita --install org.dita-community.pdf-page-break</code></pre>
</div>
</li></ol></section>
<section class="example"><div class="tasklabel"><h2 class="sectiontitle tasklabel">Example</h2></div>
<p class="p">The <span class="ph filepath">docsrc/samples</span> folder in the DITA-OT installation directory contains a complete
example:</p>
<figure class="fig fignone"><figcaption><span class="fig--title-label">Figure 1. </span>Sample Dockerfile with custom plug-ins: <span class="ph filepath"><var class="keyword varname">dita-ot-dir</var>/docsrc/samples</span><span class="ph filepath">/docker/Dockerfile</span></figcaption>
<pre class="pre codeblock language-dockerfile normalize-space show-line-numbers show-whitespace"><code># Use the latest official DITA-OT image as parent: ↓
FROM docker.pkg.github.com/dita-ot/dita-ot/dita-ot:3.6
# Install a custom plug-in from a remote location:
RUN dita --install https://github.com/infotexture/dita-bootstrap/archive/3.4.1.zip
# Install from the registry at dita-ot.org/plugins:
RUN dita --install org.dita-community.pdf-page-break</code></pre>
</figure>
</section>
<section class="example"><h2 class="title sectiontitle">Building a new image</h2>
<p class="p">You can build a Docker image from this example by running the following command from the <span class="ph filepath"><var class="keyword varname">dita-ot-dir</var>/docsrc/samples</span> directory:</p>
<pre class="pre codeblock syntax-bash"><code>$ <span class="keyword cmdname">docker</span> image build -t sample-docker-image:1.0 .
Sending build context to Docker daemon 2.048kB
Step 1/3 : FROM docker.pkg.github.com/dita-ot/dita-ot/dita-ot:<span class="keyword">3.6</span>
---&gt; 9abb96827538
Step 2/3 : RUN dita --install https://github.com/infotexture/dita-bootstrap/archive/3.4.1.zip
---&gt; Running in d510f874cae0
Added net.infotexture.dita-bootstrap
Removing intermediate container d510f874cae0
---&gt; 63deb8e15b5b
Step 3/3 : RUN dita --install org.dita-community.pdf-page-break
---&gt; Running in b4ef2fcad916
Added org.dita-community.pdf-page-break
Removing intermediate container b4ef2fcad916
---&gt; 402885636b7f
Successfully built 402885636b7f
Successfully tagged sample-docker-image:1.0
</code></pre>
<p class="p">Docker steps through each instruction in the Dockerfile to build the sample image. In this case, the
<span class="keyword cmdname">dita</span> command provides feedback on each installed plug-in.</p>
</section>
<section class="example"><h2 class="title sectiontitle">Running the new container</h2>
<p class="p">You can then start a container based on your new image:</p>
<pre class="pre codeblock syntax-bash"><code>$ <span class="keyword cmdname">docker</span> container run -it \
-v /path/to/dita-ot-dir/docsrc:/src sample-docker-image:1.0 \
-i /src/userguide.ditamap \
-o /src/out/dita-bootstrap \
-f html5-bootstrap -v</code></pre>
<div class="p">This command sequence specifies the following options:
<ul class="ul">
<li class="li"><span class="keyword option">-v</span> mounts the <span class="ph filepath">docsrc</span> subfolder of the DITA-OT directory on your host
machine and binds it to the <span class="ph filepath">/src</span> volume in the container</li>
<li class="li"><span class="keyword option">-i</span> specifies <span class="ph filepath"><var class="keyword varname">dita-ot-dir</var>/docsrc</span><span class="ph filepath">/userguide.ditamap</span> as the input map file</li>
<li class="li"><span class="keyword option">-o</span> writes the output to <span class="ph filepath"><var class="keyword varname">dita-ot-dir</var>/docsrc</span><span class="ph filepath">/out/dita-bootstrap</span></li>
<li class="li"><span class="keyword option">-f</span> sets the output format to the Bootstrap template, and</li>
<li class="li"><span class="keyword option">-v</span> displays build progress messages with verbose logging</li>
</ul>
</div>
<p class="p">When the build is finished, you should find a copy of the DITA-OT documentation under <span class="ph filepath"><var class="keyword varname">dita-ot-dir</var>/docsrc</span><span class="ph filepath">/out/dita-bootstrap</span>, styled with the basic Bootstrap
template from the custom plug-in.</p>
</section>
</div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/using-docker-images.html" title="Docker is a platform used to build, share, and run portable application containers. As of version 3.4, the DITA-OT project provides an official Docker container image that includes everything you need to run the toolkit and publish DITA content from a containerized environment.">Running the dita command from a Docker image</a></div></div></nav></article></main></body></html>

18
dita-ot-3.6/doc/topics/custom-plugins.html Normal file
View file

@ -0,0 +1,18 @@
<!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="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."><meta name="keywords" content="DITA, specializations, plug-ins"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Creating custom plug-ins</title></head><body id="custom-plugins"><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 class="active"><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></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">Creating custom plug-ins</h1>
<div class="body conbody"><p class="shortdesc">In addition to adding plug-ins from the plug-in registry at
<a class="xref" href="https://www.dita-ot.org/plugins" target="_blank" rel="external noopener">dita-ot.org/plugins</a>, 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.</p>
<p class="p">A plug-in consists of a directory, typically stored within the <span class="ph filepath">plugins/</span> subdirectory of the
DITA-OT installation. Every plug-in is controlled by a file named <span class="ph filepath">plugin.xml</span>, which is
located in the root directory of the plug-in.</p>
</div>
<nav role="navigation" class="related-links"><ul class="ullinks"><li class="link ulchildlink"><strong><a href="../topics/plugin-benefits.html">Plug-in benefits</a></strong><br>Plug-ins allow you to extend the toolkit in a way that is consistent, easy-to-share, and possible to preserve through toolkit upgrades.</li><li class="link ulchildlink"><strong><a href="../topics/plugin-configfile.html">Plug-in descriptor file</a></strong><br>The plug-in descriptor file (<span class="ph filepath">plugin.xml</span>) controls all aspects of a plug-in, making each extension visible to the rest of the toolkit. The file uses pre-defined extension points to locate changes, and then integrates those changes into the core DITA-OT code.</li><li class="link ulchildlink"><strong><a href="../topics/plugin-coding-conventions.html">Plug-in coding conventions</a></strong><br>To ensure custom plug-ins work well with the core toolkit code and remain compatible with future releases, the DITA Open Toolkit project recommends that plug-ins use modern development practices and common coding patterns.</li><li class="link ulchildlink"><strong><a href="../topics/plugin-dependencies.html">Plug-in dependencies</a></strong><br>A DITA-OT plug-in can be dependent on other plug-ins. Prerequisite plug-ins are installed first, which ensures that DITA-OT handles XSLT overrides correctly.</li><li class="link ulchildlink"><strong><a href="../topics/plugin-use-cases.html">Plug-in use cases</a></strong><br>Plug-ins allow you to extend the functionality of DITA-OT. This might entail adding support for specialized document types, integrating processing overrides, or defining new output transformations.</li><li class="link ulchildlink"><strong><a href="../topics/html-customization-plugins.html">Custom HTML plug-ins</a></strong><br>In addition to the basic modifications that can be made with parameter settings and property files, you can create custom HTML plug-ins that bundle custom fonts, JavaScript, and stylesheets; modify the HTML markup, or override other aspects of HTML processing.</li><li class="link ulchildlink"><strong><a href="../topics/pdf-customization-plugins.html">Custom PDF plug-ins</a></strong><br>In most cases, PDF output should be customized by creating custom DITA-OT plug-ins that build on the default DITA to PDF transformation. PDF plug-ins can customize covers and page layouts, modify formatting, override the logic of the default PDF plug-in, and much more.</li><li class="link ulchildlink"><strong><a href="../topics/globalization.html">Globalizing DITA content</a></strong><br>The DITA standard supports content that is written in or translated to any language. In general, DITA Open Toolkit passes content through to the output format unchanged. DITA-OT uses the values for the <code class="keyword markupname xmlatt">@xml:lang</code> and <code class="keyword markupname xmlatt">@dir</code> attributes that are set in the source content to provide globalization support. You can create custom plug-ins to support additional languages.</li><li class="link ulchildlink"><strong><a href="../topics/migration.html">Migrating customizations</a></strong><br>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. </li></ul><div class="linklist relinfo"><strong>Related information</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="https://www.oxygenxml.com/events/2018/dita-ot_day.html#step_by_step_implementation_of_a_DITA" target="_blank" rel="external noopener" title="There are lots of DITA-OT extension points, maybe list some of the most common ones, then based on 3-4 use cases implement small plugins which use those extension points. For example: a plugin which changes the default label value for &#34;Note&#34;a plugin which adds an XHTML customization matching a DITA element with a certain @status attribute value and producing a certain HTML spana plugin which customizes the PDF processing in some waya plugin which adds a specialization DTD with an XML catalog">Step by step implementation of a DITA Open Toolkit plugin</a></li></ul></div></nav></article></main></body></html>

25
dita-ot-3.6/doc/topics/determining-version-of-ditaot.html Normal file
View file

@ -0,0 +1,25 @@
<!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="You can determine the DITA Open Toolkit version number from a command prompt."><meta name="keywords" content="macOS, DITA-OT version, Linux, Windows, command line, checking DITA-OT version, installing, check current version"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Checking the DITA-OT version number</title></head><body id="determining-version-of-dita-ot"><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><ul><li><a href="../topics/prerequisite-software.html">Prerequisite software</a></li><li class="active"><a href="../topics/determining-version-of-ditaot.html">Checking the version</a></li><li><a href="../topics/first-build-using-dita-command.html">Building output</a></li><li><a href="../topics/installing-via-homebrew.html">Installing via Homebrew</a></li></ul></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></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">Checking the DITA-OT version number</h1>
<div class="body taskbody"><p class="shortdesc">You can determine the DITA Open Toolkit version number from a command prompt.</p>
<section><div class="tasklabel"><h2 class="sectiontitle tasklabel">Procedure</h2></div><ol class="ol steps"><li class="li step stepexpand">
<span class="ph cmd">Open a command prompt or terminal session.</span>
</li><li class="li step stepexpand">
<span class="ph cmd">Issue the following command:</span>
<div class="itemgroup stepxmp">
<pre class="pre codeblock"><code><span class="ph filepath"><span class="keyword cmdname">dita</span></span> <span class="keyword parmname">--version</span></code></pre>
</div>
</li></ol></section>
<section class="section result"><div class="tasklabel"><h2 class="sectiontitle tasklabel">Results</h2></div>
<p class="p">The DITA-OT version number appears on the console:</p>
<pre class="pre codeblock"><code><samp class="ph systemoutput sysout">DITA-OT version <span class="keyword">3.6</span></samp></code></pre>
</section>
</div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/installing-client.html" title="The DITA-OT distribution package can be installed on Linux, macOS, and Windows. It contains everything that you need to run the toolkit except for Java.">Installing DITA Open Toolkit</a></div></div></nav></article></main></body></html>

18
dita-ot-3.6/doc/topics/dita-and-dita-ot-resources.html Normal file
View file

@ -0,0 +1,18 @@
<!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="In addition to the DITA Open Toolkit documentation, there are other resources about DITA and DITA-OT that you might find helpful."><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>DITA and DITA-OT resources</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></li><li><a href="../topics/troubleshooting-overview.html">Troubleshooting</a></li><li><a href="../reference/index.html">Reference</a></li><li class="active"><a href="../topics/dita-and-dita-ot-resources.html">Resources</a><ul><li><a href="../topics/dita-ot-day-videos.html">DITA-OT Day Videos</a></li></ul></li></ul></nav><main role="main"><article role="article" aria-labelledby="ariaid-title1">
<h1 class="title topictitle1" id="ariaid-title1">DITA and DITA-OT resources</h1>
<p class="shortdesc">In addition to the DITA Open Toolkit documentation, there are other resources about DITA and DITA-OT that
you might find helpful.</p>
<nav role="navigation" class="related-links"><ul class="ullinks"><li class="link ulchildlink"><strong><a href="https://www.dita-ot.org" target="_blank" rel="external noopener">DITA-OT project website: dita-ot.org</a></strong><br>The DITA-OT project website at dita-ot.org provides information about the latest toolkit releases,
including download links, release notes, and documentation for recent DITA-OT versions.</li><li class="link ulchildlink"><strong><a href="https://groups.io/g/dita-users" target="_blank" rel="external noopener">DITA Users group</a></strong><br>The original dita-users group was founded in 2004 as a Yahoo! Group and moved to Groups.io in November
2019. The mailing list addresses the needs of DITA users at all levels of experience, from beginners to experts,
and serves as a vital resource for the DITA community.</li><li class="link ulchildlink"><strong><a href="https://groups.google.com/d/forum/dita-ot-users" target="_blank" rel="external noopener">DITA-OT Users Google Group</a></strong><br>General interest DITA-OT product forum, for questions on any aspect of the toolkit — from installation
and getting started to questions about specific overrides, plug-ins, and customizations.</li><li class="link ulchildlink"><strong><a href="https://dita-ot.slack.com" target="_blank" rel="external noopener">DITA-OT Slack workspace</a></strong><br>Forum for discussion related to DITA-OT development and design. Topics in this forum are more technical
in nature, covering upcoming design or code changes. To request an invitation and join in the discussion, visit
<a class="xref" href="http://slack.dita-ot.org" target="_blank" rel="external noopener">slack.dita-ot.org</a>.</li><li class="link ulchildlink"><strong><a href="http://www.oasis-open.org/committees/dita/" target="_blank" rel="external noopener">Home page for the DITA Technical Committee</a></strong><br>The OASIS DITA Technical Committee develops the DITA standard.</li><li class="link ulchildlink"><strong><a href="http://dita-archive.xml.org/wiki/the-dita-open-toolkit" target="_blank" rel="external noopener">DITA-OT project archive</a></strong><br>The DITA-OT project archive at dita-archive.xml.org provides news about earlier toolkit releases, and
release notes for legacy versions.</li><li class="link ulchildlink"><strong><a href="../reference/books.html">Books</a></strong><br>Several DITA-related publications include information on configuring and customizing DITA Open Toolkit with detailed examples on creating custom plug-ins for PDF output.</li><li class="link ulchildlink"><strong><a href="../topics/dita-ot-day-videos.html">DITA-OT Day Conference Recordings</a></strong><br>All video recordings from each DITA-OT Day conference from 2014 onward.</li></ul></nav></article></main></body></html>

31
dita-ot-3.6/doc/topics/dita-command-help.html Normal file
View file

@ -0,0 +1,31 @@
<!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="You can access a list of subcommands and supported parameters for the dita command by passing the --help option on the command line."><meta name="keywords" content="macOS, help, Linux, Windows, command line, command, dita"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Accessing help for the dita command</title></head><body id="accessing-help-from-the-cl-tool"><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></li><li><a href="../topics/troubleshooting-overview.html">Troubleshooting</a><ul><li><a href="../topics/logging.html">Logging</a></li><li><a href="../topics/enabling-debug-mode.html">Enabling debug mode</a></li><li><a href="../topics/error-messages.html">DITA-OT error messages</a></li><li><a href="../topics/other-errors.html">Other error messages</a></li><li class="active"><a href="../topics/dita-command-help.html">Command line help</a></li><li><a href="../topics/increasing-the-jvm.html">Increasing Java memory</a></li><li><a href="../topics/reducing-processing-time.html">Speeding up builds</a></li></ul></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">Accessing help for the dita command</h1>
<div class="body taskbody"><p class="shortdesc">You can access a list of subcommands and supported parameters for the <span class="keyword cmdname">dita</span> command by
passing the <span class="keyword parmname">--help</span> option on the command line.</p>
<section><div class="tasklabel"><h2 class="sectiontitle tasklabel">Procedure</h2></div><ol class="ol steps"><li class="li step stepexpand">
<span class="ph cmd">Open a command prompt or terminal session.</span>
</li><li class="li step stepexpand">
<span class="ph cmd">Issue the following command:</span>
<div class="itemgroup stepxmp">
<pre class="pre codeblock"><code><span class="ph filepath"><span class="keyword cmdname">dita</span></span> <span class="keyword parmname">--help</span></code></pre>
</div>
</li><li class="li step stepexpand"><strong>Optional: </strong>
<span class="ph cmd">For details on the arguments and options available for each subcommand, pass the
<span class="keyword parmname">--help</span> option after the subcommand name.</span>
<div class="itemgroup stepxmp">For example: <span class="keyword cmdname">dita install</span>
<span class="keyword parmname">--help</span>.</div>
</li></ol></section>
<section class="section result"><div class="tasklabel"><h2 class="sectiontitle tasklabel">Results</h2></div>
<p class="p">A brief usage summary appears in the command-line window, along with a list of subcommands, arguments, and
options.</p>
</section>
</div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/troubleshooting-overview.html" title="This section contains information about problems that you might encounter and how to resolve them.">Error messages and troubleshooting</a></div></div><div class="linklist reltasks"><strong>Related tasks</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/build-using-dita-command.html" title="You can generate output using the dita command-line tool. Build parameters can be specified on the command line or with .properties files.">Building output using the dita command</a></li></ul></div><div class="linklist relref"><strong>Related reference</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../parameters/parameters_intro.html" title="Certain parameters apply to all DITA-OT transformations. Other parameters are common to the HTML-based transformations. Some parameters apply only to specific transformation types. These parameters can be passed as options to the dita command using the --parameter=value syntax or included in build scripts as Ant properties.">DITA-OT parameters</a></li><li class="linklist"><a class="link" href="../parameters/internal-ant-properties.html" title="Reference list of Ant properties used by DITA-OT internally.">Internal Ant properties</a></li><li class="linklist"><a class="link" href="../parameters/dita-command-arguments.html" title="The dita command takes mandatory arguments to process DITA content. Subcommands can be used to manage plug-ins, or print information about the current configuration. A series of options are available to modify the command behavior or specify additional configuration parameters.">Arguments and options for the dita command</a></li></ul></div></nav></article></main></body></html>

41
dita-ot-3.6/doc/topics/dita-ot-day-videos-intro-2014.html Normal file
View file

@ -0,0 +1,41 @@
<!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="November 20, 2014 in Munich, Germany."><meta name="keywords" content="DITA-OT Day 2014 videos"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>DITA-OT Day Conference – Munich 2014</title></head><body id="dita_ot_day_videos_intro"><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></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><ul><li><a href="../topics/dita-ot-day-videos.html">DITA-OT Day Videos</a><ul><li><a href="../topics/dita-ot-day-videos-intro-2019.html">2019 Brussels</a></li><li><a href="../topics/dita-ot-day-videos-intro-2018.html">2018 Rotterdam</a></li><li><a href="../topics/dita-ot-day-videos-intro-2017.html">2017 Berlin</a></li><li><a href="../topics/dita-ot-day-videos-intro-2016.html">2016 Munich</a></li><li><a href="../topics/dita-ot-day-videos-intro-2015.html">2015 Munich</a></li><li class="active"><a href="../topics/dita-ot-day-videos-intro-2014.html">2014 Munich</a></li></ul></li></ul></li></ul></nav><main role="main"><article role="article" aria-labelledby="ariaid-title1">
<h1 class="title topictitle1" id="ariaid-title1">DITA-OT Day Conference – Munich 2014</h1>
<div class="body conbody"><p class="shortdesc">November 20, 2014 in Munich, Germany.</p>
<p class="p"></p>
</div>
<nav role="navigation" class="related-links"><ul class="ullinks"><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2014/dita-ot_day.html#Quo_vadis" target="_blank" rel="external noopener">Quo vadis?</a></strong><br>Discussion about the present and the future of the DITA-OT project.</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2014/dita-ot_day.html#Providing_designers_a_flexible_way_to_publish_DITA_content_into_Adobe_InDesign" target="_blank" rel="external noopener">Providing Designers a Flexible Way to Publish DITA Content into Adobe InDesign</a></strong><br>This presentation shows how Mekon have implemented a plugin that provides an approach to publishing
into InDesign, providing designers the flexibility they require.</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2014/dita-ot_day.html#Publishing_DITA_content_re-used_in_different_context" target="_blank" rel="external noopener">Publishing DITA Content Re-Used in Different Context in EPUB and Eclipse Infocenter by Using
DITA-OT</a></strong><br>On the example of ice hockey rule books, we show how easy content can be re-used by creating new
context variants and how it can be published to EPUB or into an Eclipse help infocenter.</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2014/dita-ot_day.html#SCORM_wrapper_for_DITA_to_SCORM" target="_blank" rel="external noopener">SCORM Wrapper for DITA to SCORM</a></strong><br>Hal Trent of Comtech will present a SCORM wrapper developed for learning and training output, which
could be potentially donated to the DITA-OT. The wrapper incorporates the current DITA to SCORM output and adds
a layer of JavaScript with the SCORM API to integrate the output generated from the DITA-OT into an LMS. The
wrapper passes test completion status to and from the LMS and provides a much needed output for the learning and
training implementation.</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2014/dita-ot_day.html#DITA_Open_Toolkit_PDF_generation_with_CSS" target="_blank" rel="external noopener">DITA Open Toolkit PDF Generation with CSS</a></strong><br>How about producing and styling PDFs only by using CSS? Join Radu for an overview of a new, innovative,
open-source DITA-OT plugin, which produces PDF from DITA content using CSS and an XML+CSS to PDF engine such as
the Prince XML or Antenna House engines.</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2014/dita-ot_day.html#DITA_Open_Toolkit_PDF_plugins_without_fuss_muss_or_writing_XSL-FO" target="_blank" rel="external noopener">DITA Open Toolkit PDF Plugins Without Fuss, Muss, or Writing XSL-FO</a></strong><br>Did you know that you can create customized PDF plugins using an easy online tool? Join Jarno for an
overview of his plugin generator, what it produces, and his work developing the dynamic Web
interface.</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2014/dita-ot_day.html#PDFs_from_the_DITA_Open_Toolkit" target="_blank" rel="external noopener">PDFs from the DITA Open Toolkit: The Easy and the Not-so-Easy</a></strong><br>With a few simple changes, it's possible to give the DITA-OT's default PDF output much of your own look
and feel. If you need to develop a DITA proof of concept for your organization, these changes might be all you
need to get the ball rolling. Join Leigh to find out what's easy to do, what's not quite so easy to do, and
where the real heavy lifting is.</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2014/dita-ot_day.html#dita2rdf_from_trees_to_triples" target="_blank" rel="external noopener">dita2rdf: from trees to triples</a></strong><br>The dita2rdf plugin is meant to extract metadata from DITA content and produce an RDF/XML output, which
is a serialization of the W3C RDF standard. The final objective is to get insights from the DITA content by
querying its metadata as a graph, not as a tree-like in XML. It also potentially enables the connection of the
DITA metadata with other types of entities such as products, people, events, etc.</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2014/dita-ot_day.html#Extending_the_DITA_Open_Toolkit" target="_blank" rel="external noopener">Extending the DITA Open Toolkit: How crazy can you get?</a></strong><br>DITA-OT includes extension points that let you do any number of things. This session will cover what's
available, what you should or shouldn't extend, and give out sample plugins to slice and dice your
content.</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2014/dita-ot_day.html#RNG_to_DTD_and_XSD_using_the_DITA_Open_Toolkit" target="_blank" rel="external noopener">RNG to DTD and XSD using the DITA Open Toolkit</a></strong><br>The new version of DITA, version 1.3, will use Relax NG as the normative grammar to express the DITA
content models. George proposed this idea and provided a working prototype under the DITA-NG open source project
and Eliot took this further making it an official proposal for DITA 1.3 and finalized its implementation. See
how Relax NG simplifies the way DITA content models and specializations are defined and what other benefits it
brings to DITA 1.3.</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2014/dita-ot_day.html#Contributing_to_the_Toolkit_via_GitHub" target="_blank" rel="external noopener">Contributing to the Toolkit via GitHub</a></strong><br>Now that the toolkit is hosted on GitHub, it's easier than ever to contribute changes to the DITA-OT
code. Roger will demonstrate how to fork the repository, create a new branch, change the necessary files and
submit a pull request.</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2014/dita-ot_day.html#Looking_under_the_hood_of_the_DITA_Open_Toolkit" target="_blank" rel="external noopener">Looking under the hood of the DITA Open Toolkit</a></strong><br>Participate in a deeper, more technical dive with the primary DITA-OT developer. This session will
cover the pre-processing architecture of the DITA-OT and information about the output
transformations.</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2014/dita-ot_day.html#Overview_of_the_DITA_Open_Toolkit" target="_blank" rel="external noopener">Overview of the DITA Open Toolkit</a></strong><br>Are you new to the DITA-OT? Come and get an overview of what it is, how it works, its history, and the
people involved. This will be an excellent start to DITA-OT day for novices.</li></ul><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/dita-ot-day-videos.html" title="All video recordings from each DITA-OT Day conference from 2014 onward.">DITA-OT Day Conference Recordings</a></div></div></nav></article></main></body></html>

52
dita-ot-3.6/doc/topics/dita-ot-day-videos-intro-2015.html Normal file
View file

@ -0,0 +1,52 @@
<!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="November 15, 2015 in Munich, Germany."><meta name="keywords" content="DITA-OT Day 2015 videos"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>DITA-OT Day Conference – Munich 2015</title></head><body id="dita_ot_day_videos_intro"><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></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><ul><li><a href="../topics/dita-ot-day-videos.html">DITA-OT Day Videos</a><ul><li><a href="../topics/dita-ot-day-videos-intro-2019.html">2019 Brussels</a></li><li><a href="../topics/dita-ot-day-videos-intro-2018.html">2018 Rotterdam</a></li><li><a href="../topics/dita-ot-day-videos-intro-2017.html">2017 Berlin</a></li><li><a href="../topics/dita-ot-day-videos-intro-2016.html">2016 Munich</a></li><li class="active"><a href="../topics/dita-ot-day-videos-intro-2015.html">2015 Munich</a></li><li><a href="../topics/dita-ot-day-videos-intro-2014.html">2014 Munich</a></li></ul></li></ul></li></ul></nav><main role="main"><article role="article" aria-labelledby="ariaid-title1">
<h1 class="title topictitle1" id="ariaid-title1">DITA-OT Day Conference – Munich 2015</h1>
<div class="body conbody"><p class="shortdesc">November 15, 2015 in Munich, Germany.</p>
<p class="p"></p>
</div>
<nav role="navigation" class="related-links"><ul class="ullinks"><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2015/dita-ot_day.html#DITA_OT_Documentation_Update" target="_blank" rel="external noopener">DITA-OT documentation update</a></strong><br> This talk provides an overview of recent changes to the DITA-OT documentation, points out open issues,
highlights ideas for future improvements, and closes with room for suggestions from the community and a call for
contributions.</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2015/dita-ot_day.html#Multiple_OT_With_Git" target="_blank" rel="external noopener">Multiple OT with Git</a></strong><br> If you need to maintain multiple configurations of the OT for day-to-day or minute-by-minute changes
to the OT for different projects, clients, etc., you can use git to do it. There are some tricks and gotchas but
it does work.</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2015/dita-ot_day.html#Selling_DITA_With_Demo_Data" target="_blank" rel="external noopener">Selling DITA with demo data</a></strong><br> Over a couple of years, the Gnostyx team has been preparing and refining a DITA Demonstration Data
Set. It's purpose is to provide members of the community a functionally realistic data set with which to
demonstrate DITA based applications. It was made available publicly in early 2015 and has since been adopted and
used by several members of the DITA Community. This talk is really a demonstration of some of the business use
cases that we use to convince business stakeholders that DITA demands serious attention. People will learn a
little about the DITA Demonstration Data Set and some of the sales pitches that they might want to use, and to
demonstrate, in the future.</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2015/dita-ot_day.html#Publishing_With_DITA_OT_The_CMS_Perspective" target="_blank" rel="external noopener">Publishing with DITA-OT - the CMS perspective</a></strong><br> Publishing from a CMS imposes specific requirements on the DITA-OT. We will review these requirements
while showing how IXIASOFT integrated the DITA-OT into their Output Generator.</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2015/dita-ot_day.html#Parameters_Annotations_For_DITA_OT_Plugins" target="_blank" rel="external noopener">Parameters annotations for DITA-OT plugins</a></strong><br> Each DITA-OT plugin provides a set of parameters that can be configured to customize the publishing
process. As these need to be made available to users it is important to have an automated way of discovering
these parameters and additional information about them - what they represent, what values are possible, etc.
DITA-OT makes this possible by allowing parameters to be annotated.</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2015/dita-ot_day.html#How_To_Run_DITA_OT" target="_blank" rel="external noopener">How to run DITA-OT</a></strong><br> There are multiples ways to run DITA-OT and some of them are good, some are bad, and some are just
plain ugly. This presentation goes through different interfaces to DITA-OT and when to use them.</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2015/dita-ot_day.html#Creating_DITA_OT_constraint_specialisation_plugins" target="_blank" rel="external noopener">Creating DITA-OT constraint/specialisation plugins</a></strong><br>This presentation will address the problem of creating DITA constraints/specialisations to customize
DITA to meet your specific needs. We will identify a problem, create a Relax NG constraint/specialization to
solve it and convert that to DTD. All these will be packaged as a DITA-OT plugin.</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2015/dita-ot_day.html#DITA_Community" target="_blank" rel="external noopener">DITA Community</a></strong><br> The DITA Community GitHub organization serves as a general place for people to contribute DITA Open
Toolkit plugins and other DITA-related tools and utilities that are not maintained by DITA-OT or other projects.
This presentation provides an overview of the DITA Community organization, what's there today, and how you can
contribute. </li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2015/dita-ot_day.html#PDF5-ML_Plug-in" target="_blank" rel="external noopener">PDF5-ML Plug-in - features for practical use</a></strong><br>Demonstrates the following features of PDF5-ML Multiple language in one documentConditional variable
&amp; style definitionFree format cover pages</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2015/dita-ot_day.html#DITA-OT_reloaded" target="_blank" rel="external noopener">DITA-OT ... reloaded!</a></strong><br>Professional writing can require several features that the present DITA-OT (2.1.1) has not implemented.
There are several expensive plugins available as commercial products to improve that situation. Helmut Scherzer
presents a match to highly professional DITA-OT extensions which contains a list of more than 20 new powerful
features to PDF2 – offered to become part of the public DITA-OT.</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2015/dita-ot_day.html#Inside_the_black_box" target="_blank" rel="external noopener">DITA-OT: Inside the black box</a></strong><br>When creating a product, a good design is critical; in many cases, this rule applies not only to the
outside, but also to the parts inside that normal users will not see. Unfortunately, to those who looked, the
inner workings of the early toolkit seemed to have almost no design at all. In this session, we'll talk about
how Jarno has cleaned up the hidden inner workings of the toolkit -- and how everyone benefits from these
changes to things they might never see.</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2015/dita-ot_day.html#PDF_Generation_With_CSS" target="_blank" rel="external noopener">PDF generation with CSS</a></strong><br>Presenting new updates made to the DITA-OT plugin which can now be used to generate PDF from DITA and
CSS using either Prince XML or Antenna House. </li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2015/dita-ot_day.html#Markdown_plugin" target="_blank" rel="external noopener">Markdown plugin</a></strong><br>This talk introduces Jarno Elovirta’s DITA-OT Markdown plugins, which extend the DITA Open Toolkit so
you can use Markdown files directly in topic references and export existing DITA content in Markdown format for
use in other publishing systems. This makes it easier for people to contribute content to DITA publications,
enables mobile authoring workflows, facilitates review processes with less technical audiences and expands the
range of publishing options to workflows based on Markdown.</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2015/dita-ot_day.html#Why_startcmd_is_not_your_friend" target="_blank" rel="external noopener">Why "startcmd" is not your friend</a></strong><br>The startcmd batch script made it possible for many to easily use DITA-OT, but whether you realize it
or not, it's no longer really necessary. I'll briefly explain where it came from, why it was always more of a
kludge than a Feature, and how better DITA-OT designs mean it's no longer needed.</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2015/dita-ot_day.html#DITA-OT_Patterns_and_Anti-patterns" target="_blank" rel="external noopener">DITA-OT Patterns and Anti-patterns</a></strong><br>What might often seem like a good way to use or extend DITA-OT, but likely result in trouble later?
What is the alternative? This session will cover known traps that organizations have fallen into when using
DITA-OT, and suggest how to avoid those issues or (perhaps with difficulty) recover from the mistakes. The
session will leave time for discussion about other traps that audience members may have fallen into.</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2015/dita-ot_day.html#Whats_new_in_DITA-OT" target="_blank" rel="external noopener">What's new in DITA-OT</a></strong><br>What's new in DITA-OT? We'll cover major changes in both 2.1 and 2.2, with a focus on support for new
DITA 1.3 features.</li></ul><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/dita-ot-day-videos.html" title="All video recordings from each DITA-OT Day conference from 2014 onward.">DITA-OT Day Conference Recordings</a></div></div></nav></article></main></body></html>

47
dita-ot-3.6/doc/topics/dita-ot-day-videos-intro-2016.html Normal file
View file

@ -0,0 +1,47 @@
<!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="November 13, 2016 in Munich, Germany."><meta name="keywords" content="DITA-OT Day 2016 videos"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>DITA-OT Day Conference – Munich 2016</title></head><body id="dita_ot_day_videos_intro"><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></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><ul><li><a href="../topics/dita-ot-day-videos.html">DITA-OT Day Videos</a><ul><li><a href="../topics/dita-ot-day-videos-intro-2019.html">2019 Brussels</a></li><li><a href="../topics/dita-ot-day-videos-intro-2018.html">2018 Rotterdam</a></li><li><a href="../topics/dita-ot-day-videos-intro-2017.html">2017 Berlin</a></li><li class="active"><a href="../topics/dita-ot-day-videos-intro-2016.html">2016 Munich</a></li><li><a href="../topics/dita-ot-day-videos-intro-2015.html">2015 Munich</a></li><li><a href="../topics/dita-ot-day-videos-intro-2014.html">2014 Munich</a></li></ul></li></ul></li></ul></nav><main role="main"><article role="article" aria-labelledby="ariaid-title1">
<h1 class="title topictitle1" id="ariaid-title1">DITA-OT Day Conference – Munich 2016</h1>
<div class="body conbody"><p class="shortdesc">November 13, 2016 in Munich, Germany.</p>
<p class="p"></p>
</div>
<nav role="navigation" class="related-links"><ul class="ullinks"><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2016/dita-ot_day.html#DITA_2016_Panel_Quo_Vadis" target="_blank" rel="external noopener">Panel</a></strong><br></li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2016/dita-ot_day.html#Long_term_DITA-OT_planning" target="_blank" rel="external noopener">Long term DITA-OT planning</a></strong><br>Kris and Robert will discuss the long term future of DITA-OT: what can we all do to ensure the
continued health of this critical piece of the overall DITA infrastructure? </li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2016/dita-ot_day.html#DITA_to_resolved_DITA_transformation" target="_blank" rel="external noopener">The use-cases for a "DITA to resolved DITA" transformation</a></strong><br>A DITA to simplified/resolved DITA transformation provides a solution for some of the possible issues
with translating DITA. There are also other advantages, especially in connection to the increased dynamics in
DITA-OT development. Join me to discover how a DITA to resolved DITA can help you! </li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2016/dita-ot_day.html#DITA_terminology_management_checking" target="_blank" rel="external noopener">DITA terminology management and checking</a></strong><br>I'd like to present how we manage and check terminology using the org.doctales.terminology
plugin.</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2016/dita-ot_day.html#Codeblock_Quality_Assurance_instead_of_Errata" target="_blank" rel="external noopener">Codeblock Quality Assurance instead of Errata</a></strong><br>Fixing errors during authoring stage is cheap in both technical communication and software development;
fixing errors after publishing is expensive. In this talk I demonstrate a QA method for software documentation
in DITA.</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2016/dita-ot_day.html#Testing_in_DITA-OT" target="_blank" rel="external noopener">Testing in DITA-OT</a></strong><br>Jarno and Robert will discuss how the DITA-OT is tested, get feedback and talk about where we want to
go.</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2016/dita-ot_day.html#Large_Scale_Production_Using_Project_Maps" target="_blank" rel="external noopener">Large Scale Production Using Project Maps</a></strong><br>This presentation will show how SAP has integrated the DITA Open Toolkit to create a large scale
production infrastructure able to create daily builds producing 50 000+ outputs for all SAP Product
documentation. This covers the end-to-end process from getting the DITA content from the CMS to publishing the
produced outputs to the appropriate delivery channels, using so-called project maps as a key ingredient.
Advanced features like peer linking across outputs will be shown, as part of the overall implementation. </li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2016/dita-ot_day.html#Using_the_Open_Toolkit_Through_Docker_Containers" target="_blank" rel="external noopener">Using the Open Toolkit Through Docker Containers</a></strong><br>Docker containers make it easy to package and use different configurations of software components.
Docker containers can also provide the dependencies needed to run a given piece of software. For the Open
Toolkit, you can use Docker containers to easily provision and run the Open Toolkit without worrying about the
local Java configuration or other dependencies. Docker also makes it easy to set up custom configurations of the
Open Toolkit or use different versions. This presentation shows how to use Docker-based Open Toolkit
packages.</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2016/dita-ot_day.html#Upgrading_PDF_plugins_to_DITA_OT_2.x" target="_blank" rel="external noopener">Gotcha! Upgrading PDF plugins to DITA-OT 2.x</a></strong><br>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.</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2016/dita-ot_day.html#How_the_docs_are_done" target="_blank" rel="external noopener">Documentation Development(s)</a></strong><br>This talk provides an overview of recent changes to the DITA-OT documentation, points out open issues,
highlights ideas for future improvements, and closes with room for suggestions from the community, a call for
contributions and a brief demonstration of the pull request approval process that is applied when people submit
changes to the development documentation via the /Edit this Page/ links. </li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2016/dita-ot_day.html#Simplified_contribution_process_for_the_DITA-OT_documentation" target="_blank" rel="external noopener">Simplified contribution process for the DITA-OT documentation</a></strong><br>Now it is very easy to contribute to the DITA-OT documentation - just read the developer docs and use
the "Edit" button to open the source topic from GitHub for editing. Save will automate all the contribution
process, sending a pull request with your proposed changes.</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2016/dita-ot_day.html#DITA-OT_internals_and_future_development_plans" target="_blank" rel="external noopener">DITA-OT internals and future development plans</a></strong><br>The internals of DITA-OT are in perpetual motion and most of these changes are not visible to end
users. In this talk we go through changes in the black box and describe future development plans.</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2016/dita-ot_day.html#Seven_Open-Source_DITA-OT_plugins" target="_blank" rel="external noopener">Seven open-source DITA-OT plugins developed by Oxygen</a></strong><br> This session shows 7 DITA Open Toolkit open source plugins that the developers of Oxygen XML have
created or updated this year including: DITA + CSS = PDF - This pre-existing plugin now was updated to add
support for showing Oxygen track changes and comments. DITA Classic PDF Review - This plugin adds support for
showing Oxygen track changes and comments in the classic PDF output. Media Support Plugin - Plugin which adds
the possibility to embed videos (including YouTube videos) and audio resources in DITA topics and publish to
HTML and PDF. DITA Merged - Plugin which produces a single merged XML file from the entire DITA content. DITA
Relax NG Defaults - Plugin which adds support to a DITA-OT distribution to process Relax NG-based topics and
maps. </li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2016/dita-ot_day.html#DITA-OT_Who_does_what" target="_blank" rel="external noopener">Internationalization and the DITA-OT: Who does what?</a></strong><br>While tools can be used to simplify many things, localization can still be scary. In this session,
we'll go over how the toolkit is set up to handle publishing in multiple languages: what comes out of the box?
What should you expect to do on your own? And how has this changed over the last few releases? Also: stories of
panic from the past!</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2016/dita-ot_day.html#New_DITA-OT_2.4_Release_Announcement" target="_blank" rel="external noopener">New DITA-OT 2.4 Release Announcement</a></strong><br></li></ul><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/dita-ot-day-videos.html" title="All video recordings from each DITA-OT Day conference from 2014 onward.">DITA-OT Day Conference Recordings</a></div></div></nav></article></main></body></html>

52
dita-ot-3.6/doc/topics/dita-ot-day-videos-intro-2017.html Normal file
View file

@ -0,0 +1,52 @@
<!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="October 29, 2017 in Berlin, Germany."><meta name="keywords" content="DITA-OT Day 2017 videos"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>DITA-OT Day Conference – Berlin 2017</title></head><body id="dita_ot_day_videos_intro"><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></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><ul><li><a href="../topics/dita-ot-day-videos.html">DITA-OT Day Videos</a><ul><li><a href="../topics/dita-ot-day-videos-intro-2019.html">2019 Brussels</a></li><li><a href="../topics/dita-ot-day-videos-intro-2018.html">2018 Rotterdam</a></li><li class="active"><a href="../topics/dita-ot-day-videos-intro-2017.html">2017 Berlin</a></li><li><a href="../topics/dita-ot-day-videos-intro-2016.html">2016 Munich</a></li><li><a href="../topics/dita-ot-day-videos-intro-2015.html">2015 Munich</a></li><li><a href="../topics/dita-ot-day-videos-intro-2014.html">2014 Munich</a></li></ul></li></ul></li></ul></nav><main role="main"><article role="article" aria-labelledby="ariaid-title1">
<h1 class="title topictitle1" id="ariaid-title1">DITA-OT Day Conference – Berlin 2017</h1>
<div class="body conbody"><p class="shortdesc">October 29, 2017 in Berlin, Germany.</p>
<p class="p"></p>
</div>
<nav role="navigation" class="related-links"><ul class="ullinks"><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2017/dita-ot_day.html#DITA_2017_Panel" target="_blank" rel="external noopener">Panel: What's next for DITA-OT?</a></strong><br></li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2017/dita-ot_day.html#What_are_we_missing" target="_blank" rel="external noopener">What are we missing? Where would you like to see us go?</a></strong><br>This is a feedback session where we want to hear from you! One problem with DITA-OT development is that
we don't usually know what our customers like most, what they're using, and (almost as important) what they're
not using. It's also likely that in some cases, we're not sure what to ask. In this session we'll discuss
potential ways of getting this feedback, related issues such as data privacy, and ideally take suggestions from
the audience for improved communication.</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2017/dita-ot_day.html#DCQL" target="_blank" rel="external noopener">DCQL - the Dita Cascading Query Language</a></strong><br>Short overview of the DCQL attribute domain and accompanying code that allows pulling DITA content in
from SQL or XML databases at publish time or runtime, and even keeping the data link alive on interactive media. </li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2017/dita-ot_day.html#Open_Toolkit" target="_blank" rel="external noopener">Locale-Aware Sorting and Text Handling in the Open Toolkit</a></strong><br>Presents the DITA Community i18n Plugin, which provides an integration with the ICU4J libraries. The
i18n plugin provides support for locale-specific grouping and sorting, including dictionary-based Simplified
Chinese, as well as facilities for doing locale-specific word and line breaking. </li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2017/dita-ot_day.html#Review_Docs" target="_blank" rel="external noopener">Automatically Create Targeted Review Docs for your SMEs</a></strong><br>This presentation illustrates how an OT plugin can leverage CMS status information to create a PDF for
review that includes only the content SMEs need to look at, or alternatively, include everything for full
context but highlight the specific content that needs reviewing. This presentation demonstrates how to quickly
create a PDF that includes material for a specific reviewer, and how to create a PDF intended for multiple
reviewers with their names assigned to each topic.</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2017/dita-ot_day.html#Bootstrapping_DITA" target="_blank" rel="external noopener">Bootstrapping DITA - Customizing HTML output for modern web frameworks</a></strong><br> Web developers often use CSS frameworks, HTML5 boilerplate or component libraries like Bootstrap or
Foundation to quickly build robust, responsive sites. With custom HTML plug-ins, DITA-OT can be extended to
produce HTML5 output that makes use of these common templates so that generated documents can build on existing
front-end solutions. This talk will outline the process, using the DITA-OT project website at dita-ot.org as an
example.</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2017/dita-ot_day.html#Using_CSS_to_style_the_PDF_output" target="_blank" rel="external noopener">Using CSS to style the PDF output</a></strong><br> Using CSS to produce PDF from DITA content is way easier than writing plugins and customizing XSLT
stylesheet and will probably become in the future the most used way to produce a PDF. We will go over the
existing solutions for producing PDF from DITA using CSS and maybe try to show a little bit of the CSS
pagination standard: change the front matter and backmatter, change headers and footers, change some colors and
styles, change the paper type and orientation.</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2017/dita-ot_day.html#Markdown_support_inside-out" target="_blank" rel="external noopener">Markdown support inside-out</a></strong><br>Description of how Markdown support was added to DITA-OT to make Markdown a first-class file format for
DITA content. Focus is on the implementation details and goals instead of Markdown author
perspective.</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2017/dita-ot_day.html#DITA-OT_Docs_Development" target="_blank" rel="external noopener">DITA-OT Docs Development(s)</a></strong><br>This talk provides an overview of DITA-OT documentation usage metrics and highlights recent changes to
the docs and ideas for future improvements. We’ll close with room for suggestions from the community and a call
for contributions with information on the browser-based workflow for suggesting changes.</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2017/dita-ot_day.html#Managing_a_large_scale_build_environment" target="_blank" rel="external noopener">Managing a large scale build environment with 50+ custom plugins</a></strong><br>Tips and tricks, mistakes made, and lessons learned: how IBM manages a single build environment for
hundreds of authors with 50+ plugins -- including new doctypes, new transform types, and externally contributed
plugins -- while keeping up with the latest DITA-OT releases. </li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2017/dita-ot_day.html#Generating_SVG_syntax_diagrams" target="_blank" rel="external noopener">Generating SVG syntax diagrams with plugins for all output formats</a></strong><br>DITA includes a lot of markup for syntax diagrams, but it's not particularly useful without a way to
render the diagrams. Many years ago Deborah Pickett wrote a group of plugins to render those diagrams as SVG,
but they were tied to the "html+" transform type and required an obsolete version of DITA-OT. Last year IBM
extracted the SVG diagram feature from those plugins, brought it up to date, and made it usable by other formats
(including PDF and EPUB). This session will give an overview of Deborah's original plugins, and explain how
anybody can use the updated versions with the latest DITA-OT.</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2017/dita-ot_day.html#DITA_Validation_and_spell-checking" target="_blank" rel="external noopener">DITA Validation and spell-checking</a></strong><br> Jason will discuss and demonstrate how HERE Technologies extends DITA-OT using open-sourced plugins to
continuously validate and build technical documentation. See: https://github.com/heremaps/dita-ot-plugins for
more details. The discussion will cover the design and evolution of the plugins, interaction with end users and
how you can integrate the plugins in your own workflows, as well as expected future developments. </li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2017/dita-ot_day.html#Accessibility_DITA-OT" target="_blank" rel="external noopener">Accessibility in DITA-OT</a></strong><br> Not only is accessible content often mandatory, it's also just a good idea -- assuming you want your
content available to as many readers as possible. This session provides an overview of the accessibility
features in output generated by the DITA-OT. While many features are automated thanks to the semantic nature of
DITA elements, others rely on you to make sure your content includes everything it needs to. While going over
these features, we will explain how DITA-OT handles your content, while also giving tips for how to ensure your
content reaches users on all sorts of devices. </li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2017/dita-ot_day.html#preprocess_2" target="_blank" rel="external noopener">We shall call it preprocess2</a></strong><br>Overview of preprocess2, the replacement module for the original preprocessing routines. This session
explains the new approach, why we developed it, and why should you care.</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2017/dita-ot_day.html#DITA_Announcement" target="_blank" rel="external noopener">DITA-OT</a></strong><br>A quick announcement about the DITA-OT project.</li></ul><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/dita-ot-day-videos.html" title="All video recordings from each DITA-OT Day conference from 2014 onward.">DITA-OT Day Conference Recordings</a></div></div></nav></article></main></body></html>

74
dita-ot-3.6/doc/topics/dita-ot-day-videos-intro-2018.html Normal file
View file

@ -0,0 +1,74 @@
<!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="November 4, 2018 in Rotterdam, Netherlands."><meta name="keywords" content="DITA-OT Day 2018 videos"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>DITA-OT Day Conference – Rotterdam 2018</title></head><body id="dita_ot_day_videos_intro"><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></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><ul><li><a href="../topics/dita-ot-day-videos.html">DITA-OT Day Videos</a><ul><li><a href="../topics/dita-ot-day-videos-intro-2019.html">2019 Brussels</a></li><li class="active"><a href="../topics/dita-ot-day-videos-intro-2018.html">2018 Rotterdam</a></li><li><a href="../topics/dita-ot-day-videos-intro-2017.html">2017 Berlin</a></li><li><a href="../topics/dita-ot-day-videos-intro-2016.html">2016 Munich</a></li><li><a href="../topics/dita-ot-day-videos-intro-2015.html">2015 Munich</a></li><li><a href="../topics/dita-ot-day-videos-intro-2014.html">2014 Munich</a></li></ul></li></ul></li></ul></nav><main role="main"><article role="article" aria-labelledby="ariaid-title1">
<h1 class="title topictitle1" id="ariaid-title1">DITA-OT Day Conference – Rotterdam 2018</h1>
<div class="body conbody"><p class="shortdesc">November 4, 2018 in Rotterdam, Netherlands.</p>
<p class="p"></p>
</div>
<nav role="navigation" class="related-links"><ul class="ullinks"><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2018/dita-ot_day.html#DITA_2018_Panel" target="_blank" rel="external noopener">What's next for DITA-OT?</a></strong><br></li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2018/dita-ot_day.html#who_are_you_calling" target="_blank" rel="external noopener">Who are you calling “stale” ‽</a></strong><br>The DITA-OT issue tracker contains a backlog of open issues, many of which have not been updated in
several years, and may no longer apply to recent versions. This session will discuss options for removing
outdated issues from the backlog to help focus resources on issues that are most important to users.</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2018/dita-ot_day.html#twisted_xslt_tricks" target="_blank" rel="external noopener">Twisted XSLT Tricks: Making Column Switching Work for FOP</a></strong><br>Switching from single column to two-column layout is almost impossible using the PDF2 transform and FOP
because FOP enforces XSL-FO's rule that only direct children of fo:flow can change the column spanning.
Likewise, splitting page sequences to change from portrait to landscape is hard to do with the PDF2 transform
because it provides no easy way to change the page sequence within the context of a topic's body (e.g., to put
rotated tables on landscape pages). This talk presents a general XSLT technique for splitting a single tree into
multiple trees, enabling changing column spanning and splitting page sequences with a minimum of rework of
normal templates.</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2018/dita-ot_day.html#DITA-OT_and_docOps" target="_blank" rel="external noopener">DITA-OT and DocOps</a></strong><br>Developing documentation concurrent with the software using DITA-OT in VSTS environment at
Shell.</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2018/dita-ot_day.html#apply_your_style_guide_rules_during_the_publication" target="_blank" rel="external noopener">Validation meets publication - Apply your style guide rules during the publication</a></strong><br>DITA-OT warns about technical issues in the input. Why not warn about style guide violations? This talk
shows how Schematron can be used to check topics and maps after the preprocessing phase and stop the build if
content does not pass the defined quality gates.</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2018/dita-ot_day.html#fast_path_for_building_data_assets_from_DITA" target="_blank" rel="external noopener">A fast path for building data assets from DITA</a></strong><br>Structured content can save the day when product complexity gets in the way. Let's see how DITA content
fits into an external database using the org.dita.normalize transformation as base. DITA-OT can be packaged in
different ways to prepare dev/test environment setups for IT and developer contributors.</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2018/dita-ot_day.html#overview_of_dita-semia_open-source_plugins_for_DITA-OT" target="_blank" rel="external noopener">Overview of dita-semia open-source plugins for DITA-OT</a></strong><br>I have created some DITA-OT plugins that are available as open-source (github.com/dita-semia). And I'd
like to give an overview of them: 1) postprocessing: Zip the output or set the pdf filename dynamically
depending on some content. 2) topic-num: Add numbers to topics, figures and tables (especially for HTML output).
3) image-convert: Convert images for compatibility (e.g. SVG to PNG for HTML output). 4) pdf: Yet another pdf
layout working with FOP. 5) diff: Compare two versions of a document and highlight the differences.resolver:
Resolve custom attributes (usually set as defaults be the schema) to standard DITA content, e.g. by applying an
XSLT transformation to some content, add static text content or resolve identifiers to cross
references.</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2018/dita-ot_day.html#unit_testing_DITA-OT_plugin_extensions" target="_blank" rel="external noopener">Unit Testing DITA-OT Plugin Extensions</a></strong><br>I have created a Unit Testing Framework for DITA-OT Plugins
https://github.com/jason-fox/fox.jason.unit-test - This is a DITA-OT Plugin to test DITA-OT Plugins. The
complete functionality would include HTML and command line test results, ANT script profiling, XSL template code
coverage, e automated CI testing - integration with Travis, and how to write maintainable tests swiftly and
painlessly.</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2018/dita-ot_day.html#step_by_step_implementation_of_a_DITA" target="_blank" rel="external noopener">Step by step implementation of a DITA Open Toolkit plugin</a></strong><br>There are lots of DITA-OT extension points, maybe list some of the most common ones, then based on 3-4
use cases implement small plugins which use those extension points. For example: a plugin which changes the
default label value for "Note"a plugin which adds an XHTML customization matching a DITA element with a certain
@status attribute value and producing a certain HTML spana plugin which customizes the PDF processing in some
waya plugin which adds a specialization DTD with an XML catalog</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2018/dita-ot_day.html#meta_DITA_samples" target="_blank" rel="external noopener">Meta DITA samples: testing around the edge cases</a></strong><br>Over the past few years I've developed a number of test cases that are exhaustive but on very specific
features. The sample files are not well suited for automated testing, but can often be used to manually test
custom plugins. In this lightning talk, I'll describe the samples that exist today, and also solicit feedback on
other similar test sets that might prove useful.</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2018/dita-ot_day.html#plug-in_installation_made_easier" target="_blank" rel="external noopener">Plug-in installation made easier</a></strong><br>Description and a demo of the new DITA-OT plug-in repository.</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2018/dita-ot_day.html#installing_DITA-OT_on_macOS_via_homebrew" target="_blank" rel="external noopener">Installing DITA-OT on macOS via Homebrew</a></strong><br>A new alternative installation method can now be used to install DITA-OT on macOS via the platform's
most popular open-source package manager. This talk explains the benefits of this approach, highlights key
differences to the default installation via .zip archive and demonstrates the new installation
process.</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2018/dita-ot_day.html#comparison_between_the_DocBook_and_DITA" target="_blank" rel="external noopener">Comparison between the DocBook and DITA publishing systems</a></strong><br>Let's compare side by side look at how the Docbook and DITA publishing systems work. This could give us
some ideas about future directions for DITA publishing. The presentation could be structured like this: Main
target audiences for Docbook and DITA vocabularies. Maybe initially discuss a little the Docbook and DITA
vocabularies, the ways in which Docbook handled new versions, how DITA tried to have all versions backward
compatible, the choice not to have a namespace for DITA elements. Show how Docbook solved the problem with
supporting both Docbook 4 and Docbook 5 standards. The Docbook @version attribute. 1) Pure XSLT-based processing
versus the melange of ANT + Java + XSLT which is the DITA Open Toolkit. How parameters can be discovered and
set. Also discuss how many parameters are available by default to be set for Docbook. Maybe ask people if they
want more params available by default for DITA processing. Show some examples with how a simple XSLT
customization for the HTML output can be accomplished in both systems. Also discuss disadvantages of pure XSLT
based publishing approaches, impossibility of copying resources (images for example) to an output folder for
example. 2) Adding new elements/attributes to Docbook and DITA. If you change Docbook in any way, it can no
longer be named Docbook 3) User's guides. A very decent user's manual structured a bit like a tutorial binding
together the Docbook specs, extending the vocabulary + publishing part:. The DITA-OT documentation only contains
documentation about the publishing part. 4) Profiling (filtering content). For example Docbook allows you to
filter content based on any attribute (even on xml:lang). 5) Discuss new ideas to be implemented in DITA, after
they were originally used in the DocBook publishing system:a) Index pages creating when using Apache FOP b) The
Docbook WebHelp project (Javascript-based search). c) Syntax highlight in code blocks d) Olinks (linking between
publications) e) You can add xlink:href on any Docbook element converting it to a link. f) Custom Processing
instructions which can change the publishing.</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2018/dita-ot_day.html#DITA_gradle_and_git" target="_blank" rel="external noopener">DITA, Gradle and Git: a small team approach to publishing</a></strong><br>At L-Acoustics we adopted an open source toolchain to automate our publishing process. With the CI
capabilities of GitLab and the dita-ot-gradle and saxon-gradle plugins developed by Eero Helenius, we have
created a comprehensive publishing solution suited to the needs of our small teams. One important feature of our
system is the handling of DITA-OT plugin dependencies. This architecture has facilitated the use of DITA by our
SMEs and marketing writers since from their point of view they just have to produce content and the output
"magically" appears.</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2018/dita-ot_day.html#DITA_website_survey_results" target="_blank" rel="external noopener">DITA-OT Website Survey Results</a></strong><br>This session presents the results of a survey of www.dita-ot.org website users conducted in summer
2018. Topic areas included user happiness with the current website, how often and how the site is used, in what
formats users desire the DITA-OT documentation, etc.</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2018/dita-ot_day.html#highlights_in_recent_DITA" target="_blank" rel="external noopener">Highlights in recent DITA-OT versions</a></strong><br>The core developers present an overview of the changes in DITA Open Toolkit within the past year and
highlight new features that may be of particular interest to users.</li></ul><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/dita-ot-day-videos.html" title="All video recordings from each DITA-OT Day conference from 2014 onward.">DITA-OT Day Conference Recordings</a></div></div></nav></article></main></body></html>

51
dita-ot-3.6/doc/topics/dita-ot-day-videos-intro-2019.html Normal file
View file

@ -0,0 +1,51 @@
<!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="November 9, 2019 in Brussels, Belgium."><meta name="keywords" content="DITA-OT Day 2019 videos, videos"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>DITA-OT Day Conference – Brussels 2019</title></head><body id="dita_ot_day_videos_intro"><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></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><ul><li><a href="../topics/dita-ot-day-videos.html">DITA-OT Day Videos</a><ul><li class="active"><a href="../topics/dita-ot-day-videos-intro-2019.html">2019 Brussels</a></li><li><a href="../topics/dita-ot-day-videos-intro-2018.html">2018 Rotterdam</a></li><li><a href="../topics/dita-ot-day-videos-intro-2017.html">2017 Berlin</a></li><li><a href="../topics/dita-ot-day-videos-intro-2016.html">2016 Munich</a></li><li><a href="../topics/dita-ot-day-videos-intro-2015.html">2015 Munich</a></li><li><a href="../topics/dita-ot-day-videos-intro-2014.html">2014 Munich</a></li></ul></li></ul></li></ul></nav><main role="main"><article role="article" aria-labelledby="ariaid-title1">
<h1 class="title topictitle1" id="ariaid-title1">DITA-OT Day Conference – Brussels 2019</h1>
<div class="body conbody"><p class="shortdesc">November 9, 2019 in Brussels, Belgium.</p>
<p class="p"></p>
</div>
<nav role="navigation" class="related-links"><ul class="ullinks"><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2019/dita-ot_day.html#dita_ot_shop_talk" target="_blank" rel="external noopener">DITA-OT Shop Talk</a></strong><br>Join us for an inside view of the DITA Open Toolkit project workshop: Who’s on duty; what’s on the
workbench; shavings, chips, and sawdust on the cutting room floor; management negotiations with union
representatives; annual guild membership drive, and a few ideas for what comes next.</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2019/dita-ot_day.html#easy_as_pie_pdf_customizations_using_css" target="_blank" rel="external noopener">Easy as pie PDF customizations using CSS</a></strong><br> CSS can be used to produce quality PDF and using CSS to style the PDF output is much easier than using
XSLT stylesheets. We'll explore various scenarios (changing fonts, changing the paper size, rotating pages,
flagging content) and see how easily this can be done using CSS. </li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2019/dita-ot_day.html#generating_metrics" target="_blank" rel="external noopener">Generating metrics from your DITA project</a></strong><br> The DITA Map Metrics Report plugin can be used to generate all kinds of interesting metrics from your
DITA project. We'll explore what the plugin can offer and then use the plugin to build graphics which show
metrics evolve between various versions of the user's manual. </li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2019/dita-ot_day.html#case_study_of_taxonomy_and_search" target="_blank" rel="external noopener">Case Study of Taxonomy and Search for DITA-OT</a></strong><br> The DITA-OT website was the case study organization for my master's thesis. In this session we'll talk
about what data and metrics influenced the taxonomy used to create the index, how Subject Scheme is used to
control @outputclass values, how Algolia DocSearch is causing findability problems, and recommendations for
improvements. </li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2019/dita-ot_day.html#documentation_developments" target="_blank" rel="external noopener">Documentation Developments</a></strong><br> This talk provides an overview of recent changes to the DITA-OT documentation and project website,
points out open issues, highlights ideas for future improvements, and closes with room for suggestions from the
community and a call for contributions. </li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2019/dita-ot_day.html#the_art_of_doing_nothing" target="_blank" rel="external noopener">The Art of doing nothing</a></strong><br> Standard DITA-OT pre-processing assumes that all input files are of a processable format (e.g. DITA
topics, lwDITA, hDITA etc). This session demonstrates the use of a series of DITA-OT pass-through plugins, which
avoid DITA-OT pre-processing and extend possible input formats for chapters and topics to a wider range of
standard documentation formats used by developers and non-technical experts (e.g. Word documents, Swagger
specifications, Postman collections etc.):1) fox.jason.passthrough, 2) fox.jason.passthrough.pandoc, 3)
fox.jason.passthrough.swagger</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2019/dita-ot_day.html#all_the_cool_kids_are_using_the_cloud" target="_blank" rel="external noopener">All the cool kids are using the Cloud</a></strong><br> Demonstration of two new DITA-OT transforms showing how to create novel XML-based intermediate outputs
and consume cloud-based services. The two new transforms cover DITA-to-speech and intelligent natural language
translation of text based on semantic DITA markup:1) fox.jason.audiobook, 2)
fox.jason.translate.xliff</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2019/dita-ot_day.html#all_the_cool_kids_are_using_javascript" target="_blank" rel="external noopener">All the cool kids are using JavaScript</a></strong><br> Demonstration of a series of DITA-OT plugins combining the use of JavaScript with ANT and XSLT. An
architectural discussion on how to design, test and integrate JavaScript-based functions within DITA-OT Plugins
and how to split the code between different programming languages and appropriate use of extension points. The
plugins include a syntax-highlighter and a DITA prettifier:1) fox.jason.splash, 2) fox.jason.prismjs, 3)
fox.jason.readthedocs, 4) fox.jason.pretty-dita</li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2019/dita-ot_day.html#editing_dita_open_toolkit_project_files" target="_blank" rel="external noopener">Editing DITA Open Toolkit Project files</a></strong><br> DITA Open Toolkit project files can store the entire set of main DITA Maps, output formats and
parameters necessary for publishing your DITA project. We'll explore how an XML editing tool can provide
editing, validation and publishing support for the project file. </li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2019/dita-ot_day.html#one_file_to_rule" target="_blank" rel="external noopener">One file to rule them all (DITA Project)</a></strong><br> DITA-OT 3.4 introduces support for project files to define reusable input context and publications. We
discuss why the feature was developed, how to use them and in the darkness bind them. </li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2019/dita-ot_day.html#ah_wml_dita_to_word_plug-in" target="_blank" rel="external noopener">AH-WML DITA-to-Word Plug-in</a></strong><br>AH-WML is a DITA-OT plug-in that generates Microsoft Word Document (.docx) from DITA contents. It is a
work in progress, but it already supports multiple image formats (GIF, PNG, JPEG, TIFF, EMF, SVG (Word 2016 or
later)), CALS table rendering, and several standard DITA elements (&lt;p&gt;, &lt;ul&gt;, &lt;ol&gt;,
&lt;dl&gt;, &lt;pre&gt;). </li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2019/dita-ot_day.html#various_useful_open_source_plugins" target="_blank" rel="external noopener">Various useful Open source plugins to enhance DITA publishing</a></strong><br> The DITA Open Toolkit publishing engine has support for plugins which can be installed to customize or
enhance the publishing process. In time Syncro Soft (the company which produces Oxygen XML Editor) has developed
and made open source lots of small plugins which can be installed in the publishing engine. I will be presenting
small examples in order to show case what each plugin in the Oxygen XML GitHub organization does and maybe give
you ideas about how you could use these open source plugins on your side. </li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2019/dita-ot_day.html#running_on_someone_else_computer" target="_blank" rel="external noopener">Running on someone else’s computer</a></strong><br> Description and demo of how to deploy DITA-OT on AWS, using Batch, Lambda, DynamoDB, and API Gateway
to run the process and orchestrate the deployment with CDK. </li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2019/dita-ot_day.html#trim_your_toolkit" target="_blank" rel="external noopener">Trim your toolkit with this one weird trick!</a></strong><br> DITA-OT has now been under development for over fifteen years. If you started customizing DITA-OT with
the first release to support plug-ins, even those plug-ins could be over a decade old. So what should we all be
doing to keep our tools clean? In this session, we will talk about how DITA-OT has grown: a brief history of how
we got where we are, past efforts to handle technical debt, what we all might do to help make it easier to
manage (or get rid of) that debt. </li><li class="link ulchildlink"><strong><a href="https://www.oxygenxml.com/events/2019/dita-ot_day.html#news_and_announcements" target="_blank" rel="external noopener">News and Announcements</a></strong><br></li></ul><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/dita-ot-day-videos.html" title="All video recordings from each DITA-OT Day conference from 2014 onward.">DITA-OT Day Conference Recordings</a></div></div></nav></article></main></body></html>

13
dita-ot-3.6/doc/topics/dita-ot-day-videos.html Normal file
View file

@ -0,0 +1,13 @@
<!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="All video recordings from each DITA-OT Day conference from 2014 onward."><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>DITA-OT Day Conference Recordings</title></head><body id="dita_ot_day_videos"><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></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><ul><li class="active"><a href="../topics/dita-ot-day-videos.html">DITA-OT Day Videos</a><ul><li><a href="../topics/dita-ot-day-videos-intro-2019.html">2019 Brussels</a></li><li><a href="../topics/dita-ot-day-videos-intro-2018.html">2018 Rotterdam</a></li><li><a href="../topics/dita-ot-day-videos-intro-2017.html">2017 Berlin</a></li><li><a href="../topics/dita-ot-day-videos-intro-2016.html">2016 Munich</a></li><li><a href="../topics/dita-ot-day-videos-intro-2015.html">2015 Munich</a></li><li><a href="../topics/dita-ot-day-videos-intro-2014.html">2014 Munich</a></li></ul></li></ul></li></ul></nav><main role="main"><article role="article" aria-labelledby="ariaid-title1">
<h1 class="title topictitle1" id="ariaid-title1">DITA-OT Day Conference Recordings</h1>
<div class="body conbody"><p class="shortdesc">All video recordings from each DITA-OT Day conference from 2014 onward.</p>
<p class="p"></p>
</div>
<nav role="navigation" class="related-links"><ul class="ullinks"><li class="link ulchildlink"><strong><a href="../topics/dita-ot-day-videos-intro-2019.html">Brussels 2019</a></strong><br>November 9, 2019 in Brussels, Belgium.</li><li class="link ulchildlink"><strong><a href="../topics/dita-ot-day-videos-intro-2018.html">Rotterdam 2018</a></strong><br>November 4, 2018 in Rotterdam, Netherlands.</li><li class="link ulchildlink"><strong><a href="../topics/dita-ot-day-videos-intro-2017.html">Berlin 2017</a></strong><br>October 29, 2017 in Berlin, Germany.</li><li class="link ulchildlink"><strong><a href="../topics/dita-ot-day-videos-intro-2016.html">Munich 2016</a></strong><br>November 13, 2016 in Munich, Germany.</li><li class="link ulchildlink"><strong><a href="../topics/dita-ot-day-videos-intro-2015.html">Munich 2015</a></strong><br>November 15, 2015 in Munich, Germany.</li><li class="link ulchildlink"><strong><a href="../topics/dita-ot-day-videos-intro-2014.html">Munich 2014</a></strong><br>November 20, 2014 in Munich, Germany.</li></ul><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/dita-and-dita-ot-resources.html" title="Are you new to the DITA-OT? Come and get an overview of what it is, how it works, its history, and the people involved. This will be an excellent start to DITA-OT day for novices.">Overview of the DITA Open Toolkit</a></div></div></nav></article></main></body></html>

18
dita-ot-3.6/doc/topics/dita-xml-input.html Normal file
View file

@ -0,0 +1,18 @@
<!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 Open Toolkit supports all released versions of the OASIS DITA specification, including 1.0, 1.1, 1.2, and 1.3. As of release 3.6, DITA-OT also provides an initial preview of features for the latest draft of the upcoming DITA 2.0 standard."><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Standard DITA XML</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><ul><li class="active"><a href="../topics/dita-xml-input.html">Standard DITA XML</a></li><li><a href="../topics/markdown-input.html">Markdown content</a></li><li><a href="../topics/lwdita-input.html">Lightweight DITA</a></li><li><a href="../topics/markdown-dita-syntax-reference.html">Markdown DITA syntax</a></li></ul></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></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">Standard DITA XML</h1>
<div class="body"><p class="shortdesc">DITA Open Toolkit supports all released versions of the OASIS DITA specification, including 1.0, 1.1, 1.2,
and 1.3. As of release <span class="keyword">3.6</span>, DITA-OT also provides an initial preview of features for the
latest draft of the upcoming DITA 2.0 standard.</p>
<p class="p">The DITA specification “defines a set of document types for authoring and organizing topic-oriented information,
as well as a set of mechanisms for combining, extending, and constraining document types.” The
<a class="xref" href="http://docs.oasis-open.org/dita/dita/v1.3/dita-v1.3-part0-overview.html" target="_blank" rel="external noopener">DITA 1.3 specification</a> is the authoritative source of information on authoring DITA content in XML.</p>
<div class="note tip note_tip"><span class="note__title">Tip:</span> For details on how DITA Open Toolkit processes DITA XML content, see
<a class="xref" href="../reference/dita-spec-support.html" title="DITA Open Toolkit 3.6 supports all versions of the OASIS DITA specification, including 1.0, 1.1, 1.2, and 1.3.">DITA specification support</a>.</div>
</div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/input-formats.html" title="In addition to standard DITA XML, DITA-OT supports several alternative input formats, including Markdown and the proposed XDITA, MDITA and HDITA authoring formats currently in development for Lightweight DITA.">Authoring formats</a></div></div><div class="linklist relinfo"><strong>Related information</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/markdown-input.html" title="Markdown is a lightweight markup language that allows you to write using an easy-to-read plain text format and convert to structurally valid markup as necessary.">Markdown content</a></li><li class="linklist"><a class="link" href="../topics/lwdita-input.html" title="DITA-OT provides preview support for the authoring formats proposed for Lightweight DITA, or “LwDITA”. The XDITA, MDITA and HDITA formats are alternative representations of DITA content in XML, Markdown and HTML5.">Preview support for Lightweight DITA</a></li><li class="linklist"><a class="link" href="../topics/markdown-dita-syntax-reference.html" title="Markdown DITA uses CommonMark as the underlying markup language.">Markdown DITA syntax reference</a></li></ul></div></nav></article></main></body></html>

48
dita-ot-3.6/doc/topics/dita2dita.html Normal file
View file

@ -0,0 +1,48 @@
<!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="The dita transformation generates normalized topics and maps from DITA input. The normalized output includes the results of DITA Open Toolkit pre-processing operations, which resolve map references, keys, content references, code references and push metadata back and forth between maps and topics."><meta name="keywords" content="command, dita, normalized DITA, transformations, DITA, normalized, metadata, map, topic, plug-ins, dita2dita, relationship tables, converting lightweight formats to DITA"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Normalized DITA</title></head><body id="normalized-dita"><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><ul><li><a href="../topics/dita2pdf.html">PDF</a></li><li><a href="../topics/dita2html5.html">HTML5</a></li><li><a href="../topics/dita2eclipsehelp.html">Eclipse help</a></li><li><a href="../topics/dita2htmlhelp.html">HTML Help</a></li><li><a href="../topics/dita2markdown.html">Markdown</a></li><li class="active"><a href="../topics/dita2dita.html">Normalized DITA</a></li><li><a href="../topics/dita2xhtml.html">XHTML</a></li></ul></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></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">Normalized DITA</h1>
<div class="body"><p class="shortdesc">The <code class="ph codeph">dita</code> transformation generates normalized topics and maps from DITA input. The
normalized output includes the results of DITA Open Toolkit pre-processing operations, which resolve map references,
keys, content references, code references and push metadata back and forth between maps and topics.</p>
<p class="p">In comparison to the source DITA files, the normalized DITA files are modified in the following ways:</p>
<ul class="ul">
<li class="li">References from one DITA map to another are resolved</li>
<li class="li">Map-based links, such as those generated by map hierarchy and relationship tables, are added to the
topics.</li>
<li class="li">Link text is resolved.</li>
<li class="li">Map attributes that cascade are made explicit on child elements.</li>
<li class="li">Map metadata such as index entries and copyrights are pushed into topics.</li>
<li class="li">Topic metadata such as navigation titles, link text and short descriptions are pulled from topics into the
map.</li>
<li class="li">XML comments are removed.</li>
</ul>
<section class="section" id="normalized-dita__applications"><h2 class="title sectiontitle">Applications</h2>
<p class="p">Normalized output may be useful in situations where post-processing of DITA content is required, but the
downstream systems are limited in their ability to resolve DITA references.</p>
<div class="note tip note_tip"><span class="note__title">Tip:</span> You can also use the normalized DITA transformation to convert
<a class="xref" href="markdown-input.html" title="Markdown is a lightweight markup language that allows you to write using an easy-to-read plain text format and convert to structurally valid markup as necessary.">Markdown</a> or
<a class="xref" href="lwdita-input.html" title="DITA-OT provides preview support for the authoring formats proposed for Lightweight DITA, or “LwDITA”. The XDITA, MDITA and HDITA formats are alternative representations of DITA content in XML, Markdown and HTML5.">Lightweight DITA</a> formats to DITA XML. You can then copy the generated DITA
files from the output folder to your project and replace references to the lightweight topics with their XML
equivalents.</div>
</section>
<section class="section" id="normalized-dita__generating-normalized-dita-output"><h2 class="title sectiontitle">Generating normalized DITA output</h2>
<p class="p">Run the <span class="keyword cmdname">dita</span> command and set the value of the output <span class="keyword parmname">--format</span> option to
<span class="keyword option">dita</span>:</p>
<pre class="pre codeblock"><code><span class="ph filepath"><span class="keyword cmdname">dita</span></span> <span class="keyword parmname">--input</span>=<var class="keyword varname">input-file</var> <span class="keyword parmname">--format</span>=<span class="keyword option">dita</span></code></pre>
<p class="p">where:</p>
<ul class="ul">
<li class="li"><var class="keyword varname">input-file</var> is the DITA map or DITA file that you want to
process.</li>
</ul>
</section>
</div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/output-formats.html" title="DITA Open Toolkit ships with several core transformations that convert DITA content to different output formats. Additional formats are available from the plug-in registry at dita-ot.org/plugins.">DITA-OT transformations (output formats)</a></div></div><div class="linklist relref"><strong>Related reference</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../parameters/parameters-base.html" title="Certain parameters apply to all transformations that DITA Open Toolkit supports.">Common parameters</a></li></ul></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#DITA_to_resolved_DITA_transformation" target="_blank" rel="external noopener" title="A DITA to simplified/resolved DITA transformation provides a solution for some of the possible issues with translating DITA. There are also other advantages, especially in connection to the increased dynamics in DITA-OT development. Join me to discover how a DITA to resolved DITA can help you!">The use-cases for a "DITA to resolved DITA" transformation</a></li></ul></div></nav></article></main></body></html>

44
dita-ot-3.6/doc/topics/dita2eclipsehelp.html Normal file
View file

@ -0,0 +1,44 @@
<!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="The eclipsehelp transformation generates XHTML output, CSS files, and the control files that are needed for Eclipse help."><meta name="keywords" content="transformations, Eclipse Help, Eclipse Help, transformations, plug-ins, dita2eclipsehelp, CSS, table of contents"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Eclipse help</title></head><body id="dita2eclipsehelp"><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><ul><li><a href="../topics/dita2pdf.html">PDF</a></li><li><a href="../topics/dita2html5.html">HTML5</a></li><li class="active"><a href="../topics/dita2eclipsehelp.html">Eclipse help</a></li><li><a href="../topics/dita2htmlhelp.html">HTML Help</a></li><li><a href="../topics/dita2markdown.html">Markdown</a></li><li><a href="../topics/dita2dita.html">Normalized DITA</a></li><li><a href="../topics/dita2xhtml.html">XHTML</a></li></ul></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></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">Eclipse help</h1>
<div class="body conbody"><p class="shortdesc">The <span class="keyword option">eclipsehelp</span> transformation generates XHTML output, CSS files, and the control files
that are needed for Eclipse help.</p>
<p class="p">In addition to the XHTML output and CSS files, this transformation returns the following files, where
<var class="keyword varname">mapname</var> is the name of the master DITA map.</p>
<table class="simpletable table-hover frame-all"><colgroup><col style="width:40%"><col style="width:60%"></colgroup><thead><tr class="sthead">
<th class="stentry" scope="col" id="dita2eclipsehelp__stentry__1">File name</th>
<th class="stentry" scope="col" id="dita2eclipsehelp__stentry__2">Description</th>
</tr></thead><tbody><tr class="strow">
<td class="stentry" headers="dita2eclipsehelp__stentry__1"><span class="ph filepath">plugin.xml</span></td>
<td class="stentry" headers="dita2eclipsehelp__stentry__2">Control file for the Eclipse plug-in</td>
</tr><tr class="strow">
<td class="stentry" headers="dita2eclipsehelp__stentry__1"><span class="ph filepath"><var class="keyword varname">mapname</var>.xml</span></td>
<td class="stentry" headers="dita2eclipsehelp__stentry__2">Table of contents</td>
</tr><tr class="strow">
<td class="stentry" headers="dita2eclipsehelp__stentry__1"><span class="ph filepath">index.xml</span></td>
<td class="stentry" headers="dita2eclipsehelp__stentry__2">Index file</td>
</tr><tr class="strow">
<td class="stentry" headers="dita2eclipsehelp__stentry__1"><span class="ph filepath">plugin.properties</span></td>
<td class="stentry" headers="dita2eclipsehelp__stentry__2"></td>
</tr><tr class="strow">
<td class="stentry" headers="dita2eclipsehelp__stentry__1"><span class="ph filepath">META-INF/MANIFEST.MF</span></td>
<td class="stentry" headers="dita2eclipsehelp__stentry__2"></td>
</tr></tbody></table>
<p class="p">To run the Eclipse help transformation, set the <span class="keyword parmname">transtype</span> parameter to
<span class="keyword option">eclipsehelp</span>, or pass the <span class="keyword parmname">--format</span>=<span class="keyword option">eclipsehelp</span> option to
the <span class="keyword cmdname">dita</span> command line.</p>
<pre class="pre codeblock"><code><span class="ph filepath"><span class="keyword cmdname">dita</span></span> <span class="keyword parmname">--input</span>=<var class="keyword varname">input-file</var> <span class="keyword parmname">--format</span>=<span class="keyword option">eclipsehelp</span></code></pre>
<p class="p">where:</p>
<ul class="ul">
<li class="li"><var class="keyword varname">input-file</var> is the DITA map or DITA file that you want to
process.</li>
</ul>
</div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/output-formats.html" title="DITA Open Toolkit ships with several core transformations that convert DITA content to different output formats. Additional formats are available from the plug-in registry at dita-ot.org/plugins.">DITA-OT transformations (output formats)</a></div></div><div class="linklist relconcepts"><strong>Related concepts</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../parameters/generate-copy-outer.html" title="By default, DITA-OT assumes content is located in or beneath the directory containing the DITA map file. The generate.copy.outer parameter can be used to adjust how output is generated for content that is located outside the map directory.">Handling content outside the map directory</a></li></ul></div><div class="linklist relref"><strong>Related reference</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../parameters/parameters-base.html" title="Certain parameters apply to all transformations that DITA Open Toolkit supports.">Common parameters</a></li><li class="linklist"><a class="link" href="../parameters/parameters-base-html.html" title="Certain parameters apply to all HTML-based transformation types: HTML5, XHTML, HTML&nbsp;Help, and Eclipse help.">HTML-based output parameters</a></li><li class="linklist"><a class="link" href="../parameters/parameters-eclipsehelp.html" title="Certain parameters are specific to the Eclipse help transformation.">Eclipse Help parameters</a></li></ul></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/2014/dita-ot_day.html#Publishing_DITA_content_re-used_in_different_context" target="_blank" rel="external noopener" title="On the example of ice hockey rule books, we show how easy content can be re-used by creating new context variants and how it can be published to EPUB or into an Eclipse help infocenter.">Publishing DITA Content Re-Used in Different Context in EPUB and Eclipse Infocenter by Using
DITA-OT</a></li><li class="linklist"><a class="link" href="http://www.eclipse.org" target="_blank" rel="external noopener">Official Eclipse website</a></li></ul></div></nav></article></main></body></html>

26
dita-ot-3.6/doc/topics/dita2html5.html Normal file
View file

@ -0,0 +1,26 @@
<!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="The html5 transformation generates HTML5 output and a table of contents (TOC) file."><meta name="keywords" content=", nav, languages, right-to-left, HTML, HTML5, HTML5, transformations, transformations, plug-ins, dita2html5, CSS, CSS, table of contents"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>HTML5</title></head><body id="dita2html5"><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><ul><li><a href="../topics/dita2pdf.html">PDF</a></li><li class="active"><a href="../topics/dita2html5.html">HTML5</a></li><li><a href="../topics/dita2eclipsehelp.html">Eclipse help</a></li><li><a href="../topics/dita2htmlhelp.html">HTML Help</a></li><li><a href="../topics/dita2markdown.html">Markdown</a></li><li><a href="../topics/dita2dita.html">Normalized DITA</a></li><li><a href="../topics/dita2xhtml.html">XHTML</a></li></ul></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></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">HTML5</h1>
<div class="body conbody"><p class="shortdesc">The <span class="keyword option">html5</span> transformation generates HTML5 output and a table of contents (TOC)
file.</p>
<p class="p">The HTML5 output is always associated with the default DITA-OT CSS file (<span class="ph filepath">commonltr.css</span> or
<span class="ph filepath">commonrtl.css</span> for right-to-left languages). You can use toolkit parameters to add a custom
style sheet that overrides the default styles, or generate a <code class="keyword markupname xmlelement">&lt;nav&gt;</code> element with a
navigation TOC in topic pages.</p>
<p class="p">To run the HTML5 transformation, set the <span class="keyword parmname">transtype</span> parameter to <span class="keyword option">html5</span>, or
pass the <span class="keyword parmname">--format</span>=<span class="keyword option">html5</span> option to the <span class="keyword cmdname">dita</span> command
line.</p>
<pre class="pre codeblock"><code><span class="ph filepath"><span class="keyword cmdname">dita</span></span> <span class="keyword parmname">--input</span>=<var class="keyword varname">input-file</var> <span class="keyword parmname">--format</span>=<span class="keyword option">html5</span></code></pre>
<p class="p">where:</p>
<ul class="ul">
<li class="li"><var class="keyword varname">input-file</var> is the DITA map or DITA file that you want to
process.</li>
</ul>
</div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/output-formats.html" title="DITA Open Toolkit ships with several core transformations that convert DITA content to different output formats. Additional formats are available from the plug-in registry at dita-ot.org/plugins.">DITA-OT transformations (output formats)</a></div></div><div class="linklist relconcepts"><strong>Related concepts</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../parameters/generate-copy-outer.html" title="By default, DITA-OT assumes content is located in or beneath the directory containing the DITA map file. The generate.copy.outer parameter can be used to adjust how output is generated for content that is located outside the map directory.">Handling content outside the map directory</a></li></ul></div><div class="linklist reltasks"><strong>Related tasks</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/html-customization-parameters.html" title="For simple branded HTML pages, you can adjust the look and feel of the default output to match your company style by setting parameters to include custom CSS, header branding, or table-of-contents navigation in topics. (These changes do not require a custom plug-in.)">Setting parameters for custom HTML</a></li></ul></div><div class="linklist relref"><strong>Related reference</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../parameters/parameters-base.html" title="Certain parameters apply to all transformations that DITA Open Toolkit supports.">Common parameters</a></li><li class="linklist"><a class="link" href="../parameters/parameters-base-html.html" title="Certain parameters apply to all HTML-based transformation types: HTML5, XHTML, HTML&nbsp;Help, and Eclipse help.">HTML-based output parameters</a></li><li class="linklist"><a class="link" href="../parameters/parameters-html5.html" title="The HTML5 transformation shares common parameters with other HTML-based transformations and provides additional parameters that are specific to HTML5 output.">HTML5 parameters</a></li></ul></div></nav></article></main></body></html>

43
dita-ot-3.6/doc/topics/dita2htmlhelp.html Normal file
View file

@ -0,0 +1,43 @@
<!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="The htmlhelp transformation generates HTML output, CSS files, and the control files that are needed to produce a Microsoft Compiled HTML Help (.chm) file."><meta name="keywords" content="transformations, HTML Help, HTML Help, transformations, CHM, Microsoft HTML Help Workshop, .hhc, .hhk, .hhp, plug-ins, dita2htmlhelp, CSS, index, table of contents"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>HTML Help</title></head><body id="dita2htmlhelp"><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><ul><li><a href="../topics/dita2pdf.html">PDF</a></li><li><a href="../topics/dita2html5.html">HTML5</a></li><li><a href="../topics/dita2eclipsehelp.html">Eclipse help</a></li><li class="active"><a href="../topics/dita2htmlhelp.html">HTML Help</a></li><li><a href="../topics/dita2markdown.html">Markdown</a></li><li><a href="../topics/dita2dita.html">Normalized DITA</a></li><li><a href="../topics/dita2xhtml.html">XHTML</a></li></ul></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></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">HTML Help</h1>
<div class="body conbody"><p class="shortdesc">The <span class="keyword option">htmlhelp</span> transformation generates HTML output, CSS files, and the control files that
are needed to produce a Microsoft Compiled HTML Help (.chm) file.</p>
<p class="p">In addition to the HTML output and CSS files, this transformation returns the following files, where
<var class="keyword varname">mapname</var> is the name of the master DITA map.</p>
<table class="simpletable table-hover frame-all"><colgroup><col style="width:40%"><col style="width:60%"></colgroup><thead><tr class="sthead">
<th class="stentry" scope="col" id="dita2htmlhelp__stentry__1">File name</th>
<th class="stentry" scope="col" id="dita2htmlhelp__stentry__2">Description</th>
</tr></thead><tbody><tr class="strow">
<td class="stentry" headers="dita2htmlhelp__stentry__1"><span class="ph filepath"><var class="keyword varname">mapname</var>.hhc</span></td>
<td class="stentry" headers="dita2htmlhelp__stentry__2">Table of contents</td>
</tr><tr class="strow">
<td class="stentry" headers="dita2htmlhelp__stentry__1"><span class="ph filepath"><var class="keyword varname">mapname</var>.hhk</span></td>
<td class="stentry" headers="dita2htmlhelp__stentry__2">Sorted index</td>
</tr><tr class="strow">
<td class="stentry" headers="dita2htmlhelp__stentry__1"><span class="ph filepath"><var class="keyword varname">mapname</var>.hhp</span></td>
<td class="stentry" headers="dita2htmlhelp__stentry__2">HTML Help project file</td>
</tr><tr class="strow">
<td class="stentry" headers="dita2htmlhelp__stentry__1"><span class="ph filepath"><var class="keyword varname">mapname</var>.chm</span></td>
<td class="stentry" headers="dita2htmlhelp__stentry__2">
<p class="p">Compiled HTML Help file</p>
<div class="note note note_note"><span class="note__title">Note:</span> The compiled file is only generated if the HTML Help Workshop is installed on the build system.</div>
</td>
</tr></tbody></table>
<p class="p">To run the HTML Help transformation, set the <span class="keyword parmname">transtype</span> parameter to
<span class="keyword option">htmlhelp</span>, or pass the <span class="keyword parmname">--format</span>=<span class="keyword option">htmlhelp</span> option to the
<span class="keyword cmdname">dita</span> command line.</p>
<pre class="pre codeblock"><code><span class="ph filepath"><span class="keyword cmdname">dita</span></span> <span class="keyword parmname">--input</span>=<var class="keyword varname">input-file</var> <span class="keyword parmname">--format</span>=<span class="keyword option">htmlhelp</span></code></pre>
<p class="p">where:</p>
<ul class="ul">
<li class="li"><var class="keyword varname">input-file</var> is the DITA map or DITA file that you want to
process.</li>
</ul>
</div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/output-formats.html" title="DITA Open Toolkit ships with several core transformations that convert DITA content to different output formats. Additional formats are available from the plug-in registry at dita-ot.org/plugins.">DITA-OT transformations (output formats)</a></div></div><div class="linklist relconcepts"><strong>Related concepts</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../parameters/generate-copy-outer.html" title="By default, DITA-OT assumes content is located in or beneath the directory containing the DITA map file. The generate.copy.outer parameter can be used to adjust how output is generated for content that is located outside the map directory.">Handling content outside the map directory</a></li></ul></div><div class="linklist relref"><strong>Related reference</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../parameters/parameters-base.html" title="Certain parameters apply to all transformations that DITA Open Toolkit supports.">Common parameters</a></li><li class="linklist"><a class="link" href="../parameters/parameters-base-html.html" title="Certain parameters apply to all HTML-based transformation types: HTML5, XHTML, HTML&nbsp;Help, and Eclipse help.">HTML-based output parameters</a></li><li class="linklist"><a class="link" href="../parameters/parameters-htmlhelp.html" title="Certain parameters are specific to the Microsoft Compiled HTML Help (.chm) transformation.">Microsoft Compiled HTML Help parameters</a></li></ul></div></nav></article></main></body></html>

40
dita-ot-3.6/doc/topics/dita2markdown.html Normal file
View file

@ -0,0 +1,40 @@
<!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="Along with Markdown input, DITA-OT now provides three new transformation types to convert DITA content to Markdown, including the original syntax, GitHub-Flavored Markdown, and GitBook."><meta name="keywords" content="Markdown, transformations, GitHub-Flavored Markdown, GitBook, plug-ins, dita2markdown, table of contents"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Markdown</title></head><body id="markdown"><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><ul><li><a href="../topics/dita2pdf.html">PDF</a></li><li><a href="../topics/dita2html5.html">HTML5</a></li><li><a href="../topics/dita2eclipsehelp.html">Eclipse help</a></li><li><a href="../topics/dita2htmlhelp.html">HTML Help</a></li><li class="active"><a href="../topics/dita2markdown.html">Markdown</a></li><li><a href="../topics/dita2dita.html">Normalized DITA</a></li><li><a href="../topics/dita2xhtml.html">XHTML</a></li></ul></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></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">Markdown</h1>
<div class="body"><p class="shortdesc">Along with Markdown input, DITA-OT now provides three new transformation types to convert DITA content to
Markdown, including the original syntax, GitHub-Flavored Markdown, and GitBook.</p>
<p class="p">The new output formats can be used to feed DITA content into Markdown-based publishing systems or other workflows
that lack the ability to process DITA XML.</p>
<section class="section" id="markdown__generating-markdown-output"><h2 class="title sectiontitle">Generating Markdown output</h2>
<p class="p">Markdown output can be generated by passing one of the following transformation types to the dita command with
the <span class="keyword parmname">--format</span> option:</p>
<ul class="ul">
<li class="li">
<p class="p">To publish Markdown DITA files, use the <span class="keyword option">markdown</span> transtype.</p></li>
<li class="li">
<p class="p">To generate
<a class="xref" href="https://github.github.com/gfm/" target="_blank" rel="external noopener">GitHub-Flavored Markdown</a> files, use the <span class="keyword option">markdown_github</span> transtype.</p></li>
<li class="li">
<p class="p">To publish GitHub-Flavored Markdown and generate a <span class="ph filepath">SUMMARY.md</span> table of contents file
for publication via
<a class="xref" href="https://www.gitbook.com" target="_blank" rel="external noopener">GitBook</a>, use the
<span class="keyword option">markdown_gitbook</span> transtype.</p></li>
</ul>
<p class="p">Run the <span class="keyword cmdname">dita</span> command and set the value of the output <span class="keyword parmname">--format</span> option to
the desired format, for example:</p>
<pre class="pre codeblock"><code><span class="ph filepath"><span class="keyword cmdname">dita</span></span> <span class="keyword parmname">--input</span>=<var class="keyword varname">input-file</var> <span class="keyword parmname">--format</span>=<span class="keyword option">markdown</span></code></pre>
<p class="p">where:</p>
<ul class="ul">
<li class="li"><var class="keyword varname">input-file</var> is the DITA map or DITA file that you want to
process.</li>
</ul></section>
</div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/output-formats.html" title="DITA Open Toolkit ships with several core transformations that convert DITA content to different output formats. Additional formats are available from the plug-in registry at dita-ot.org/plugins.">DITA-OT transformations (output formats)</a></div></div><div class="linklist relref"><strong>Related reference</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../parameters/parameters-base.html" title="Certain parameters apply to all transformations that DITA Open Toolkit supports.">Common parameters</a></li></ul></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/2017/dita-ot_day.html#Markdown_support_inside-out" target="_blank" rel="external noopener" title="Description of how Markdown support was added to DITA-OT to make Markdown a first-class file format for DITA content. Focus is on the implementation details and goals instead of Markdown author perspective.">Markdown support inside-out</a></li><li class="linklist"><a class="link" href="https://www.oxygenxml.com/events/2015/dita-ot_day.html#Markdown_plugin" target="_blank" rel="external noopener" title="This talk introduces Jarno Elovirta’s DITA-OT Markdown plugins, which extend the DITA Open Toolkit so you can use Markdown files directly in topic references and export existing DITA content in Markdown format for use in other publishing systems. This makes it easier for people to contribute content to DITA publications, enables mobile authoring workflows, facilitates review processes with less technical audiences and expands the range of publishing options to workflows based on Markdown.">Markdown plugin</a></li></ul></div></nav></article></main></body></html>

23
dita-ot-3.6/doc/topics/dita2pdf.html Normal file
View file

@ -0,0 +1,23 @@
<!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="The pdf transformation generates output in Portable Document Format."><meta name="keywords" content="PDF, transformations, transformations, PDF, plug-in, history of, plug-ins, dita2pdf"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>PDF</title></head><body id="dita2pdf"><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><ul><li class="active"><a href="../topics/dita2pdf.html">PDF</a></li><li><a href="../topics/dita2html5.html">HTML5</a></li><li><a href="../topics/dita2eclipsehelp.html">Eclipse help</a></li><li><a href="../topics/dita2htmlhelp.html">HTML Help</a></li><li><a href="../topics/dita2markdown.html">Markdown</a></li><li><a href="../topics/dita2dita.html">Normalized DITA</a></li><li><a href="../topics/dita2xhtml.html">XHTML</a></li></ul></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></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">PDF</h1>
<div class="body conbody"><p class="shortdesc">The <span class="keyword option">pdf</span> transformation generates output in Portable Document Format.</p>
<p class="p">This transformation was originally created as a plug-in and maintained outside of the main toolkit code. It was
created as a more robust alternative to the demo PDF transformation in the original toolkit, and thus was known as
PDF2. The plug-in was bundled into the default toolkit distribution with release 1.4.3.</p>
<p class="p">To run the PDF transformation, set the <span class="keyword parmname">transtype</span> parameter to <span class="keyword option">pdf</span>, or pass
the <span class="keyword parmname">--format</span>=<span class="keyword option">pdf</span> option to the <span class="keyword cmdname">dita</span> command line.</p>
<pre class="pre codeblock"><code><span class="ph filepath"><span class="keyword cmdname">dita</span></span> <span class="keyword parmname">--input</span>=<var class="keyword varname">input-file</var> <span class="keyword parmname">--format</span>=<span class="keyword option">pdf</span></code></pre>
<p class="p">where:</p>
<ul class="ul">
<li class="li"><var class="keyword varname">input-file</var> is the DITA map or DITA file that you want to
process.</li>
</ul>
</div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/output-formats.html" title="DITA Open Toolkit ships with several core transformations that convert DITA content to different output formats. Additional formats are available from the plug-in registry at dita-ot.org/plugins.">DITA-OT transformations (output formats)</a></div></div><div class="linklist relconcepts"><strong>Related concepts</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/pdf2-creating-change-bars.html" title="You can generate revision bars in your PDF output by using the changebar and color attributes of the DITAVAL revprop element.">Generating revision bars</a></li></ul></div><div class="linklist relref"><strong>Related reference</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../parameters/parameters-base.html" title="Certain parameters apply to all transformations that DITA Open Toolkit supports.">Common parameters</a></li><li class="linklist"><a class="link" href="../parameters/parameters-pdf.html" title="Certain parameters are specific to the PDF transformation.">PDF parameters</a></li></ul></div></nav></article></main></body></html>

26
dita-ot-3.6/doc/topics/dita2xhtml.html Normal file
View file

@ -0,0 +1,26 @@
<!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="The xhtml transformation generates XHTML output and a table of contents (TOC) file. This was the first transformation created for DITA Open Toolkit, and originally served as the basis for all HTML-based transformations."><meta name="keywords" content="languages, right-to-left, transformations, XHTML, XHTML, transformations, HTML, plug-ins, dita2xhtml, CSS, table of contents"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>XHTML</title></head><body id="dita2xhtml"><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><ul><li><a href="../topics/dita2pdf.html">PDF</a></li><li><a href="../topics/dita2html5.html">HTML5</a></li><li><a href="../topics/dita2eclipsehelp.html">Eclipse help</a></li><li><a href="../topics/dita2htmlhelp.html">HTML Help</a></li><li><a href="../topics/dita2markdown.html">Markdown</a></li><li><a href="../topics/dita2dita.html">Normalized DITA</a></li><li class="active"><a href="../topics/dita2xhtml.html">XHTML</a></li></ul></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></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">XHTML</h1>
<div class="body conbody"><p class="shortdesc">The <span class="keyword option">xhtml</span> transformation generates XHTML output and a table of contents (TOC) file. This
was the first transformation created for DITA Open Toolkit, and originally served as the basis for all HTML-based
transformations.</p>
<p class="p">The XHTML output is always associated with the default DITA-OT CSS file (<span class="ph filepath">commonltr.css</span> or
<span class="ph filepath">commonrtl.css</span> for right-to-left languages). You can use toolkit parameters to add a custom
style sheet to override the default styles.</p>
<p class="p">To run the XHTML transformation, set the <span class="keyword parmname">transtype</span> parameter to <span class="keyword option">xhtml</span>, or
pass the <span class="keyword parmname">--format</span>=<span class="keyword option">xhtml</span> option to the <span class="keyword cmdname">dita</span> command
line.</p>
<pre class="pre codeblock"><code><span class="ph filepath"><span class="keyword cmdname">dita</span></span> <span class="keyword parmname">--input</span>=<var class="keyword varname">input-file</var> <span class="keyword parmname">--format</span>=<span class="keyword option">xhtml</span></code></pre>
<p class="p">where:</p>
<ul class="ul">
<li class="li"><var class="keyword varname">input-file</var> is the DITA map or DITA file that you want to
process.</li>
</ul>
</div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/output-formats.html" title="DITA Open Toolkit ships with several core transformations that convert DITA content to different output formats. Additional formats are available from the plug-in registry at dita-ot.org/plugins.">DITA-OT transformations (output formats)</a></div></div><div class="linklist relconcepts"><strong>Related concepts</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../parameters/generate-copy-outer.html" title="By default, DITA-OT assumes content is located in or beneath the directory containing the DITA map file. The generate.copy.outer parameter can be used to adjust how output is generated for content that is located outside the map directory.">Handling content outside the map directory</a></li></ul></div><div class="linklist reltasks"><strong>Related tasks</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/html-customization-parameters.html" title="For simple branded HTML pages, you can adjust the look and feel of the default output to match your company style by setting parameters to include custom CSS, header branding, or table-of-contents navigation in topics. (These changes do not require a custom plug-in.)">Setting parameters for custom HTML</a></li></ul></div><div class="linklist relref"><strong>Related reference</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../parameters/parameters-base.html" title="Certain parameters apply to all transformations that DITA Open Toolkit supports.">Common parameters</a></li><li class="linklist"><a class="link" href="../parameters/parameters-base-html.html" title="Certain parameters apply to all HTML-based transformation types: HTML5, XHTML, HTML&nbsp;Help, and Eclipse help.">HTML-based output parameters</a></li><li class="linklist"><a class="link" href="../parameters/parameters-xhtml.html" title="Certain parameters are specific to the XHTML transformation.">XHTML parameters</a></li></ul></div></nav></article></main></body></html>

31
dita-ot-3.6/doc/topics/enabling-debug-mode.html Normal file
View file

@ -0,0 +1,31 @@
<!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="Debug logging prints considerably more additional information. The debug log includes all information from the verbose log, plus details on Java classes, additional Ant properties and overrides, preprocessing filters, parameters, and stages, and the complete build sequence. The debug log can help you determine the root cause of a problem."><meta name="keywords" content=", property, command line, debugging, command, dita, debugging, args.debug, environment variables, stack trace, Ant"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Enabling debug mode</title></head><body id="t-enabling-debug-mode"><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></li><li><a href="../topics/troubleshooting-overview.html">Troubleshooting</a><ul><li><a href="../topics/logging.html">Logging</a></li><li class="active"><a href="../topics/enabling-debug-mode.html">Enabling debug mode</a></li><li><a href="../topics/error-messages.html">DITA-OT error messages</a></li><li><a href="../topics/other-errors.html">Other error messages</a></li><li><a href="../topics/dita-command-help.html">Command line help</a></li><li><a href="../topics/increasing-the-jvm.html">Increasing Java memory</a></li><li><a href="../topics/reducing-processing-time.html">Speeding up builds</a></li></ul></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">Enabling debug mode</h1>
<div class="body taskbody"><p class="shortdesc">Debug logging prints considerably more additional information. The debug log includes all information from
the verbose log, plus details on Java classes, additional Ant properties and overrides, preprocessing filters,
parameters, and stages, and the complete build sequence. The debug log can help you determine the root cause of a
problem.</p>
<section><div class="tasklabel"><h2 class="sectiontitle tasklabel">Procedure</h2></div><div class="ol steps"><div class="li step p">
<span class="ph cmd">From the command prompt, add the following parameters:</span>
<table border="1" frame="hsides" rules="rows" cellpadding="4" cellspacing="0" summary="" class="simpletable choicetable choicetableborder"><colgroup><col style="width:50%"><col style="width:50%"></colgroup><thead><tr class="sthead chhead"><th scope="col" class="stentry choptionhd" style="vertical-align:bottom;text-align:left;">Application</th><th scope="col" class="stentry chdeschd" style="vertical-align:bottom;text-align:left;">Parameters</th></tr></thead><tbody><tr class="strow chrow">
<th style="vertical-align:top;" scope="row" class="stentry choption"><span class="keyword cmdname">dita</span> command</th>
<td style="vertical-align:top;" class="stentry chdesc"><span class="keyword parmname">--debug</span>, <span class="keyword parmname">-debug</span>, or <span class="keyword parmname">-d</span></td>
</tr><tr class="strow chrow">
<th style="vertical-align:top;" scope="row" class="stentry choption">Ant</th>
<td style="vertical-align:top;" class="stentry chdesc"><code class="ph codeph">-v -Dargs.debug=yes</code></td>
</tr></tbody></table>
<div class="itemgroup info">
<div class="p">You also can add a <code class="keyword markupname xmlelement">&lt;property&gt;</code> element to an Ant target in your build file, for
example: <pre class="pre codeblock language-xml"><code>&lt;property name="args.debug" value="yes"/&gt;</code></pre></div>
<div class="note attention note_attention"><span class="note__title">Attention:</span> Debug logging requires additional resources and can slow down the build process, so it
should only be enabled when further details are required to diagnose problems.</div>
</div>
</div></div></section>
</div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/troubleshooting-overview.html" title="This section contains information about problems that you might encounter and how to resolve them.">Error messages and troubleshooting</a></div></div></nav></article></main></body></html>

675
dita-ot-3.6/doc/topics/error-messages-details.html Normal file
View file

@ -0,0 +1,675 @@
<!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="This topic lists each error message generated by the toolkit and provides additional information that might be helpful in understanding and resolving the error condition. If your toolkit installation includes custom plug-ins that define additional messages, you can add to this list by rebuilding the DITA-OT documentation."><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>DITA-OT error messages</title></head><body id="errormessages"><header role="banner"><div class="header">
<p>DITA Open Toolkit</p>
<hr>
</div></header><nav role="toc"><ul></ul></nav><main role="main"><article role="article" aria-labelledby="ariaid-title1">
<h1 class="title topictitle1" id="ariaid-title1">DITA-OT error messages</h1>
<div class="body refbody"><p class="shortdesc">This topic lists each error message generated
by the toolkit and provides additional information that might be helpful in understanding and resolving the error
condition. If your toolkit installation includes custom plug-ins that define additional messages, you can add to
this list by rebuilding the DITA-OT documentation.</p>
<section class="section" id="errormessages__overview">
<p class="p">Each message ID is composed of a message prefix, a message number, and a letter that indicates the severity
level (I, W, E, or F). </p>
<p class="p">The toolkit uses the following severity scale:</p>
<dl class="dl" id="errormessages__severity-levels">
<dt class="dt dlterm">Info (I)</dt>
<dd class="dd">Informational messages highlight the progress of transformation and call attention to conditions of which
you should be aware. For example, draft comments are enabled and will be rendered in the output.</dd>
<dt class="dt dlterm">Warning (W)</dt>
<dd class="dd">The toolkit encountered a problem that should be corrected. Processing will continue, but the output might
not be as expected.</dd>
<dt class="dt dlterm">Error (E)</dt>
<dd class="dd">The toolkit encountered a more severe problem, and the output is affected. For example, some content is
missing or invalid, or the content is not rendered in the output</dd>
<dt class="dt dlterm">Fatal (F)</dt>
<dd class="dd">The toolkit encountered a severe condition, processing stopped, and no output is generated.</dd>
</dl>
<p class="p">Plug-ins may be used to add additional messages to the toolkit; for more information, see
<a class="xref" href="rebuilding-docs.html" title="When you add or remove plug-ins, you can rebuild the documentation to update the information on the extension points, messages, and parameters that are available in your environment.">Rebuilding the DITA-OT documentation</a>.</p>
</section>
<table class="simpletable"><colgroup><col style="width:100%"></colgroup><thead><tr class="sthead">
<th class="stentry" scope="col" id="errormessages__stentry__1">Individual cells in this table may be used to push additional explanations for any existing error
message into the generated message topic.</th>
</tr></thead><tbody><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">To add additional explanation to any message, add the explanation to this table in a single cell, and
set the following attributes on the <code class="keyword markupname xmlelement">&lt;stentry&gt;</code> tag:
<ul class="ul">
<li class="li"><code class="ph codeph">conkeyref="error-messages/MESSAGEID-extra"</code> -- for example, use the following to add
additional info to message DOTX001F: <code class="ph codeph">conkeyref="error-messages/DOTX001F-extra"</code></li>
<li class="li"><code class="ph codeph">conaction="pushreplace"</code></li>
</ul></td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">Default transformation types that
ship with the toolkit include dita, eclipsehelp, html5, htmlhelp, markdown variants, pdf (or pdf2), and xhtml.
Additional transformation types may be available if toolkit plug-ins are installed.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">The input parameter was not
specified, so there is no DITA or DITAMAP file to transform. Ensure the parameter is set properly; see
<a class="xref" href="../parameters/parameters-base.html" title="Certain parameters apply to all transformations that DITA Open Toolkit supports.">DITA-OT common parameters (args.input)</a> if you are unsure how to specify
the input file.
</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">An alternate stylesheet was specified
to run in place of the default XSLT output process, but that stylesheet could not be loaded. Please correct
the parameter to specify a valid stylesheet.
</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">This optional parameter is used to
set an extension for DITA topic documents in the temporary processing directory. Only "dita", ".dita", "xml",
or ".xml" are allowed.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">If the CSSPATH uses an absolute path,
it should be one that can still be accessed after the files are moved to another system (such as
<code class="ph codeph">http://www.example.org/</code>). Absolute paths on the local file system will be broken if the
content is moved to a new system.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">The running footer file, which
contains content to be added to the bottom of each XHTML output topic, cannot be located or read. This is
usually caused by a typo in the parameter value. You should also ensure that the value is not specified with
"file:" as a prefix.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">The running header file, which
contains content to be added to the top of each XHTML output topic, cannot be located or read. This is usually
caused by a typo in the parameter value. You should also ensure that the value is not specified with "file:"
as a prefix.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">The running heading file, which
contains content to be added to the <code class="keyword markupname xmlelement">&lt;head&gt;</code> section of each HTML output topic, cannot be
located or read. This is usually caused by a typo in the parameter value. You should also ensure that the
value is not specified with "file:" as a prefix.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">An alternate stylesheet was specified
to run in place of the default XSL-FO output process, but that stylesheet could not be loaded. Please correct
the parameter to specify a valid stylesheet.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">According to the OASIS DITA
Specification, the <code class="keyword markupname xmlelement">&lt;index-see&gt;</code> element should be ignored if the parent
<code class="keyword markupname xmlelement">&lt;indexterm&gt;</code> contains other <code class="keyword markupname xmlelement">&lt;indexterm&gt;</code> children.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">According to the OASIS DITA
Specification, the <code class="keyword markupname xmlelement">&lt;index-see-also&gt;</code> element should be ignored if the parent
<code class="keyword markupname xmlelement">&lt;indexterm&gt;</code> contains other <code class="keyword markupname xmlelement">&lt;indexterm&gt;</code> children.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">Please ensure that the input file
path and file name were entered correctly.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1"></td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">The transform was unable to create
files properly during the transform; results may not be as expected.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">This message may indicate an invalid
input file (such as accidentally specifying a PDF file as input rather than a DITA map file), an input file
that uses elements which are not allowed, are not part or a DITA file that has errors and cannot be parsed as
XML. You could also be using a specialized DITA document type that needs external plug-ins in order to be
parsed correctly. The message issued by the XML parser should provide additional information to help diagnose
the cause.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">This message may indicate a reference
to an invalid file (such as accidentally referencing a PDF or unknown XML file as if it was DITA), a
referenced file that uses elements which are not allowed, or a referenced DITA file that has errors and cannot
be parsed as XML. You could also be using a specialized DITA document type that needs external plug-ins in
order to be parsed correctly. The message issued by the XML parser should provide additional information to
help diagnose the cause.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">An empty
<code class="keyword markupname xmlelement">&lt;indexterm&gt;</code> element was found, and will appear in the index as ***. This index term
should be removed from the source.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">This will appear when one installed
plug-in requires another in order to function correctly, but the required plug-in is not found. The installed
plug-in will be ignored.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">This may appear if filter conditions
on the root element of a topic cause the entire topic to be filtered out. To remove this message, you could
place any filter conditions on the reference to this file, which will prevent the build from accessing this
file.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">Either the input file or the ditaval
file should change, otherwise your build is explicitly excluding all content.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">Check whether the image exists in the
source location or already exists in the output directory.
</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">This message should only appear in
the following cases:
<ul class="ul">
<li class="li">Errors earlier in the transform prevented this step of the transform from running; correct any errors
and try the build again.</li>
<li class="li">An Ant build or plug-in is directly calling the toolkit’s topic merge module, and is doing so
improperly; in this case the Ant build or plug-in needs to be fixed.</li>
<li class="li">In the past, problems have been encountered when calling this module with an absolute path; this should
no longer be an issue, but may be fixed in older releases by updating the Ant build or plug-in.</li>
</ul></td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">This message should only appear if an
Ant build or plug-in is directly calling the toolkit’s topic merge module, or if earlier errors resulted in
problems with some of the content. If the topic merge module is called correctly, then this indicates a
program error that should be reported to the DITA-OT development team via the
<a class="xref" href="https://github.com/dita-ot/dita-ot/issues" target="_blank" rel="external noopener">GitHub issues tracker</a>. </td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">When referencing a non-DITA file, the
format attribute should indicate the type of file referenced (such as "html" for HTML topics or "pdf" for PDF
files). Otherwise, the transform may attempt to parse the referenced document as a DITA topic.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">The domains attribute is used in
specialized DITA documents to help determine which domain elements are legal. This message will only appear if
a DITA specialization was not defined properly.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">All specialized DITA elements must
define a class attribute to provide ancestry information. This message will only appear if a specialized DITA
element did not define a class attribute, or if non-DITA elements are included in a DITA context.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">This informational message is
intended to help you catch filter conditions that may have been specified improperly; if the value is correct,
no action is needed.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1"></td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">DITA processing is based on class
attributes defined for every element. Usually these are defaulted in the DTD or Schema; if no DTD or Schema is
used, the class attributes must be explicitly included in the map or topic.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">This will appear when a topic is
outside the scope of the map; for example, if the main input map references
<span class="ph filepath">"../other-directory/some.dita"</span>. The result would cause an output file to be created
outside of the output directory. See
<a class="xref" href="../parameters/parameters-base.html" title="Certain parameters apply to all transformations that DITA Open Toolkit supports.">DITA-OT common parameters (outer.control and generate.copy.outer)</a> for
details.
</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">This will appear when a topic is
outside the scope of the map; for example, if the main input map references
<span class="ph filepath">"../other-directory/some.dita"</span>. The result would cause an output file to be created
outside of the output directory. If you do not want to see the warning message, please use the Ant parameter
'outer.control', and set the value to "quiet". Otherwise, move the referenced file into the input dita/map
directory. See
<a class="xref" href="../parameters/parameters-base.html" title="Certain parameters apply to all transformations that DITA Open Toolkit supports.">DITA-OT common parameters (outer.control and generate.copy.outer)</a> for
details.
</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">DITA processing is based on class
attributes defined for every element. Usually these are defaulted in the DTD or Schema; if validation against
the DTD or Schema is turned off, the class attributes must be explicitly included in the map or
topic.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">This appears to indicate an error in
creating specialized metadata elements. Please verify that the document type you are using is complete and
complies with DITA Specialization rules.
</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">Please see the topic on
<a class="xref" href="http://docs.oasis-open.org/dita/dita/v1.3/os/part1-base/langRef/attributes/theconactionattribute.html#theconactionattribute" target="_blank" rel="external noopener">Conref Push</a> in the DITA specification for details on expected syntax
for this function.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">Please see the topic on
<a class="xref" href="http://docs.oasis-open.org/dita/dita/v1.3/os/part1-base/langRef/attributes/theconactionattribute.html#theconactionattribute" target="_blank" rel="external noopener">Conref Push</a> in the DITA specification for details on expected syntax
for this function.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">The conref attribute must be a URI
reference to a DITA element. Please see the topic on
<a class="xref" href="http://docs.oasis-open.org/dita/dita/v1.3/os/part1-base/archSpec/base/uri-based-addressing.html#uri-based-addressing" target="_blank" rel="external noopener">URI-based addressing</a> in the DITA specification for details on the
expected syntax.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">The conref push function was used to
replace a single element with two or more alternatives. Only one element may directly replace another using
conref push. See
<a class="xref" href="http://docs.oasis-open.org/dita/dita/v1.3/os/part1-base/langRef/attributes/theconactionattribute.html#theconactionattribute" target="_blank" rel="external noopener">Conref Push</a> in the DITA specification for more information about the
conref push "replace" function.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">The target for a conref push action
does not exist; please make sure that the syntax is correct and that the target exists. See the topic on
<a class="xref" href="http://docs.oasis-open.org/dita/dita/v1.3/os/part1-base/archSpec/base/uri-based-addressing.html#uri-based-addressing" target="_blank" rel="external noopener">URI-based addressing</a> in the DITA specification for details on the
expected syntax. If the syntax is correct, it is possible that the target was filtered out of your build using
a DITAVAL file.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">Please see the topic on
<a class="xref" href="http://docs.oasis-open.org/dita/dita/v1.3/os/part1-base/langRef/attributes/theconactionattribute.html#theconactionattribute" target="_blank" rel="external noopener">Conref Push</a> in the DITA specification for details on expected syntax
for this function.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">This informational message is
intended to help you catch catch duplicate key definitions; if the keys are defined as expected, no action is
needed.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">See
<a class="xref" href="http://docs.oasis-open.org/dita/dita/v1.3/os/part1-base/langRef/attributes/theconkeyrefattribute.html#theconkeyrefattribute" target="_blank" rel="external noopener">the conkeyref definition</a> for details on expected syntax and
usage.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">This message is intended to help you
locate incorrectly specified keys; if the key was specified correctly, this message may be ignored.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">A DITA Subject Scheme map was used to
limit values that are available to the specified attribute. Please correct the attribute so that it uses one
of the allowed values.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">The Eclipse index will contain a
value such as "See also otherEntry", but otherEntry does not exist in this index. The index reference will be
broken unless this plug-in is <em class="ph i">always</em> loaded into Eclipse with another plug-in that defines otherEntry
as an index term.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">The target for a coderef element,
which specifies an external text-based file, could not be located or loaded. Please verify that the reference
is correct.
<p class="p">Note that for security reasons, references to code samples outside of the scope of the map directory are
not supported by default, as this could allow a reference to access and display any restricted or hidden
file on the system. If you are certain that the path is valid and the file should be loaded, the current
workaround is to set a parameter to allow these references. See
<a class="xref" href="../parameters/parameters-base.html" title="Certain parameters apply to all transformations that DITA Open Toolkit supports.">DITA-OT common parameters (outer.control and generate.copy.outer)</a> for
details.
</p></td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">DITA-OT supports a special syntax on
coderef elements to specify the character set of the target document. See
<a class="xref" href="../reference/extended-functionality.html" title="DITA-OT provides additional processing support beyond that which is mandated by the DITA specification. These extensions can be used to define character encodings or line ranges for code references, normalize indendation, add line numbers or display whitespace characters in code blocks.">Extended codeblock processing</a> for details on the expected syntax.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">By default, DITA-OT supports the
extensions "dita" and "xml" for DITA topics, as mandated by the DITA specification. Please verify that your
topics use one of these extensions, or configure the toolkit to allow additional extensions.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">This message indicates that the
<code class="keyword markupname xmlatt">@href</code> value specified in <var class="keyword varname">%1</var> does not use proper URI syntax. This may
occur when <code class="keyword markupname xmlatt">@href</code> includes characters that should be escaped (such as the space character,
which should be <code class="ph codeph">%20</code> when in a URI). In strict processing mode this will cause a build
failure; in other processing modes the build will continue using the value in <var class="keyword varname">%2</var>.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">A conref "mark" action has been used
to mark a target element without a corresponding content reference target. This may occur when the order of
the "mark" element and the pushed element is reversed.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">
<p class="p">A circular reference was found in key definitions: a series of key references where the last key references
the first.</p>
<p class="p">This may occur if a <code class="keyword markupname xmlelement">&lt;topicref&gt;</code> element contains both a key name in the
<code class="keyword markupname xmlatt">@keys</code> attribute and a reference to the same key in the <code class="keyword markupname xmlatt">@keyref</code> attribute,
or if a <code class="keyword markupname xmlatt">@keyref</code> attribute points to a key that refers back to the referencing element.</p>
<p class="p">To resolve this issue, change the target of the <code class="keyword markupname xmlatt">@keyref</code> so the key is defined by pointing
to a resource other than itself.</p>
</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">
<p class="p">When a <code class="keyword markupname xmlatt">@class</code> attribute does not use the expected syntax, this usually indicates that
<code class="keyword markupname xmlatt">@class</code> has been explicitly set on a DITA element. The attribute should be removed from the
document so that the expected default value can be automatically used.</p>
<p class="p">If this is a non-DITA element, it needs to be placed inside a <code class="keyword markupname xmlelement">&lt;foreign&gt;</code> element so
that is not validated against DITA rules.
</p>
</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">
<p class="p">Ensure that the DITAVAL file exists. If more than one DITAVAL file is specified, ensure that the paths are
delimited using the file path separator character appropriate for your operating system (semicolon
‘<code class="ph codeph">;</code>’ on Windows, or colon ‘<code class="ph codeph">:</code>’ on macOS or Linux).</p>
</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">This build uses generated text, such
as the phrase "Related information" (which is generated above many link groups). The toolkit was unable to
locate the string <var class="keyword varname">%1</var> for your specified language, so the string will appear in the default
language. This generally indicates that the toolkit’s strings need to be updated to support your language, or
that your language setting is incorrect.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">The Eclipse help system requires a
title in the project files generated from your map. Please add a title to your input map to get valid Eclipse
help output.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">Eclipse uses anchor references to
connect with other TOC files. For this to work in content generated from a DITA map, the anchorref element
must reference either an existing Eclipse TOC XML file, or another DITA map (which will presumably also be
converted to an Eclipse TOC).
</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">Eclipse builds use DITA’s
<code class="keyword markupname xmlelement">&lt;navref&gt;</code> element to pull in other Eclipse TOC files. The build found a
<code class="keyword markupname xmlelement">&lt;navref&gt;</code> element that does not reference any other file; the element will be
ignored.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">To remove this message, provide a
navigation title for the referenced object in the map or topic, or ensure that you are referencing a valid
local DITA target.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">Set the format attribute to identify
the format of the file. If the reference is to a DITA document, ensure that the document uses a valid DITA
extension (default supported extensions are "dita" and "xml").</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">The HTML Help compiler will only
include some types of information in the compiled CHM file; the current reference will not be
included.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">Ensure that the file exists and can
be read. <span class="ph">Note that the name of the file in this message may have be changed
to use a standard dita topic file extension ('.dita' or '.xml'), instead of the original extension used by
the file; it may also include a path to the temporary directory rather than to the original.</span></td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">To fix the table of contents, specify
a navigation title in your map or ensure that the referenced file is local and can be accessed. <span class="ph">Note that the name of the file in this message may have be changed
to use a standard dita topic file extension ('.dita' or '.xml'), instead of the original extension used by
the file; it may also include a path to the temporary directory rather than to the original.</span>
</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">No title was found in the specified
topic, so the table of contents will use the indicated fallback value for this topic.
</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">The conref attribute must be a URI
reference to an existing DITA element. Please see the topic on
<a class="xref" href="http://docs.oasis-open.org/dita/dita/v1.3/os/part1-base/archSpec/base/uri-based-addressing.html#uri-based-addressing" target="_blank" rel="external noopener">URI-based addressing</a> in the DITA specification for details on the
expected syntax. <span class="ph" id="errormessages__changeExtension">Note that the name of the file in this message may have be changed
to use a standard dita topic file extension ('.dita' or '.xml'), instead of the original extension used by
the file; it may also include a path to the temporary directory rather than to the original.</span>
<p class="p">If the target element exists in your source file, check to make sure it is not filtered out of the build
with a DITAVAL file (which will remove the target before conref processing runs).</p></td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">When pulling content with a conref
attribute, you may only pull from a single element, but the target ID appears twice in the referenced topic.
<span class="ph">Note that the name of the file in this message may have be changed
to use a standard dita topic file extension ('.dita' or '.xml'), instead of the original extension used by
the file; it may also include a path to the temporary directory rather than to the original.</span></td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">This message is deprecated and should
no longer appear in any logs.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">This may appear if (for example) you
have a <code class="keyword markupname xmlelement">&lt;ph&gt;</code> element that references another phrase, but that phrase itself contains a
reference to the original. This will result in an infinite loop. The toolkit will stop following the conref
trail when this is detected; you will need to correct the reference in your source files. <span class="ph">Note that the name of the file in this message may have be changed
to use a standard dita topic file extension ('.dita' or '.xml'), instead of the original extension used by
the file; it may also include a path to the temporary directory rather than to the original.</span></td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">The conref attribute must be a URI
reference to a DITA element. Please see the topic on
<a class="xref" href="http://docs.oasis-open.org/dita/dita/v1.3/os/part1-base/archSpec/base/uri-based-addressing.html#uri-based-addressing" target="_blank" rel="external noopener">URI-based addressing</a> in the DITA specification for details on the
expected syntax.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">The conref attribute must be a URI
reference to a DITA element. Please see the topic on
<a class="xref" href="http://docs.oasis-open.org/dita/dita/v1.3/os/part1-base/archSpec/base/uri-based-addressing.html#uri-based-addressing" target="_blank" rel="external noopener">URI-based addressing</a> in the DITA specification for details on the
expected syntax. <span class="ph">Note that the name of the file in this message may have be changed
to use a standard dita topic file extension ('.dita' or '.xml'), instead of the original extension used by
the file; it may also include a path to the temporary directory rather than to the original.</span></td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">This warning is intended to catch
instances where a non-DITA format setting unexpectedly cascades to a DITA topic, which will prevent the topic
from being processed. To remove this message, set the format attribute directly on the indicated reference.
<span class="ph">Note that the name of the file in this message may have be changed
to use a standard dita topic file extension ('.dita' or '.xml'), instead of the original extension used by
the file; it may also include a path to the temporary directory rather than to the original.</span></td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">Found a value such as &lt;xref
href=""&gt;link text&lt;/xref&gt;. The empty href attribute is not serving a purpose and has caused problems with
some tools in the past; you should remove the attribute entirely or specify a value.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">The type attribute in DITA is
intended to describe the type of the target; for example, a reference to a concept topic may use
type="concept". Generally, this attribute is optional, and the DITA-OT build will automatically determine the
value during processing. In this case, the type attribute lists a more general type than what is actually
found. This is not an error but may result in unexpected sorting for links to this topic.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">The type attribute in DITA is
intended to describe the type of the target; for example, a reference to a concept topic may use
type="concept". Generally, this attribute is optional, and the DITA-OT build will automatically determine the
value during processing. In this case, the specified type value does not match the target, which may cause
your links to sort inappropriately.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">DITA-OT is only able to dynamically
retrieve titles when the target is a local (not peer or external) DITA resource.
</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">DITA-OT is only able to dynamically
retrieve titles when the target is a local DITA resource.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">The build was unable to get a title
from the referenced topic; instead, a navigation title will be created based on the specified
<code class="keyword markupname xmlelement">&lt;linktext&gt;</code> element inside of <code class="keyword markupname xmlelement">&lt;topicmeta&gt;</code>.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">If the target is a local DITA topic,
ensure the reference is correct and the topic is available. Otherwise, provide a navigation title, and ensure
the scope and format attributes are set appropriately.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">DITA-OT is only able to dynamically
retrieve titles and link text when the target is a local (not peer or external) DITA resource.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">DITA-OT is only able to dynamically
retrieve titles when the target is a local DITA resource.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">The referenc to this document did not
specify any link text for generated map-based links; the navigation title will be used as fallback.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">The referenced file did not specify
any link text for generated map-based links, and no fallback text could be located. Any links generated from
this reference will have incorrect link text.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">The link or cross reference has no
target specified and will not generate a link.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">The type attribute in DITA is
intended to describe the type of the target; for example, a reference to a concept topic may use
type="concept". Generally, this attribute is optional, and the DITA-OT build will automatically determine the
value during processing. In this case, the type attribute lists a more general type than what is actually
found. This is not an error but may result in unexpected sorting for links to this topic.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">The type attribute in DITA is
intended to describe the type of the target; for example, a reference to a concept topic may use
type="concept". Generally, this attribute is optional, and the DITA-OT build will automatically determine the
value during processing. In this case, the specified type value does not match the target, which may cause
your links to sort inappropriately.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">The build attempted to access the
specified file in order to retrive a title or short description, but the file could not be found. If the file
exists, it is possible that a DITAVAL file was used to remove the file’s contents from the build. Be aware
that the path information above may not match the link in your topic.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">When a link or cross reference does
not have content, the build will attempt to pull the target’s title for use as link text. If the target is
unavailable, be sure to set the scope attribute to an appropriate value. If the target does not have a title
(such as when linking to a paragraph), be sure to provide link text inside the cross reference.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">An <code class="keyword markupname xmlelement">&lt;xref&gt;</code>
element specifies type="li", which indicates a link to a list item, but the item number could not be
determined to use as link text. Please specify link text inside the reference, or ensure that you are
referencing an available list item.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">The cross reference goes to a list
item in an unordered list. The process could not automatically generate link text because the list item is not
numbered. Please provide link text within the cross reference.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">An <code class="keyword markupname xmlelement">&lt;xref&gt;</code>
element specifies type="fn", which indicates a link to a footnote, but the footnote number could not be
determined to use as link text. Please specify link text inside the reference, or ensure that you are
referencing an available footnote.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">An <code class="keyword markupname xmlelement">&lt;xref&gt;</code>
element specifies type="dlentry", which indicates a link to a definition list entry, but the term could not be
located to use as link text. Please specify link text inside the reference, or ensure that you are referencing
an available definition list entry</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">No title was found for the current
document, so the HTML output file will set the <code class="keyword markupname xmlelement">&lt;title&gt;</code> to "***". This value generally
appears in the title bar at the top of a browser.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">The <code class="keyword markupname xmlelement">&lt;object&gt;</code>
element in HTML does not support using longdescref for accessibility. To make the object accessible, you may
need to add text before or after the element. You may also be able to handle it with a
<code class="keyword markupname xmlelement">&lt;param&gt;</code> element inside the object.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">This message is generated when
creating draft output in order to help you locate all topics that need to be cleaned up; the cleanup items
will appear in your output with styling that makes it stand out. The content will be hidden when the draft
parameter is not active.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">This message is generated when
creating draft output in order to help you locate all topics that have draft comments. Each comment will
appear in your HTML output; the comments will be hidden when the draft parameter is not active.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">Because of the way XML and DITA are
defined, it is generally not possible to prohibit adding a second title to a section during editing (or to
force that title to come first). However, the DITA specification states that only one title should be used in
a section. When multiple titles are found, only the first one will appear in the output.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">If it is important to flag this piece
of information, try placing a flag on the block element that contains your phrase. If you just want to have an
image next to the phrase, you may place an image directly into the document.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">DITA-OT is able to remove duplicate
links in most cases. However, if two links to the same resource use different attributes or link text, it is
possible for them to appear together. For example, if the same link shows up with role="next" and again with
no specified role, it may show up as both the "Next topic" link and as a related link. Note that links
generated from a <code class="keyword markupname xmlelement">&lt;reltable&gt;</code> in a DITA map will have the role attribute set to "friend".
</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">The <code class="keyword markupname xmlelement">&lt;area&gt;</code>
element in an image map must provide a link target for the specified area. Please add an
<code class="keyword markupname xmlelement">&lt;xref&gt;</code> element as a child of <code class="keyword markupname xmlelement">&lt;area&gt;</code> and ensure that it
specifies a link target.
</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">Cross reference text inside the
<code class="keyword markupname xmlelement">&lt;area&gt;</code> element is used to provide accessibility for screen readers that can identify
different areas of an image map. If text cannot be retrieved automatically by referencing a DITA element, it
should be specified directly in the cross reference.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">The specified value was passed as-is
through to the <code class="keyword markupname xmlelement">&lt;area&gt;</code> element in the HTML.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">The area element is intended to
define a region in an image map; coordinates must be specified in order to define that region.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">The build will not look for peer or
external topics before compiling your CHM file, so they may not be included. If you are referencing an actual
HTML file that will not be available, it cannot be included in the project, and you should set the toc
attribute to "no" on your topicref element. Otherwise, check to be sure your HTML file was included in the
CHM; if it was not, you will need to place it in the correct location with your other output files and
recompile.
</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">The PDF, ODT, and RTF output
processes cannot automatically convert non-DITA content into DITA in order to merge it with the rest of your
content. The referenced items are ignored.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">Eclipse requires that an ID be
specified when creating an Eclipse Help project; the toolkit expects to locate that ID on the root element of
your input map.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">The toolkit is attempting to add
generated text, such as the string "Related information" that appears above links. The requested string could
not be found in any language. Your output may contain a meaningful string, or it may contain a code that was
intended to map to a string. This likely indicates an error in a plug-in or XSL override; either the string
was requested incorrectly, or you will need to provide a mapping for the string in all of the languages you
require.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">This will occur if a map references
another map, and then that second map (or another further nested map) references the original map. The result
is an infinite nesting of maps; please correct the chain of map references to remove circular
reference.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">This will occur when a DITAVAL file
contains multiple styling rules that apply to the same element.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">The "flagit" named template was
deprecated in DITA-OT version 1.4, when the OASIS standard formalized the DITAVAL syntax. The template is
removed in DITA-OT 1.6. Stylesheets that used this template need to be updated.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">The build attempted to access the
specified file in order to retrive a title or short description, but the file could not be found. If the file
exists, it is possible that a DITAVAL file was used to remove the file’s contents from the build. Another
possibility is that the file is located outside of the scope of the main input directory, and was not
available because the
<a class="xref" href="../parameters/parameters-base.html" title="Certain parameters apply to all transformations that DITA Open Toolkit supports.">onlytopic.in.map</a> parameter was specified. Be aware that the path
information above may not match the link in your topic.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">The link appears to use valid syntax
to reference a DITA element, but that element cannot be found. Please verify that the element exists, and is
not removed from the build by DITAVAL based filtering.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">Processing for terms, acronyms, or
abbreviated forms will associate the key from the element’s keyref attribute with a glossentry (glossary
entry) topic. This message will appear if the key was defined, but was not associated with a glossentry topic.
The process will try to use the best available fallback (usually the title of the referenced topic).</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">Processing for abbreviated form
elements will associate the key from the element’s keyref attribute with a glossentry (glossary entry) topic.
This message will appear if the key was defined, but was not associated with a glossentry topic. This element
is only supported with keys that are associated with glossary topics; the element will not generate any
output. Please correct the reference, or use a different element to reference your topic.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">According to the DITA Specification,
references from maps should either go to DITA Maps, DITA Topics, or any non-DITA resource. References below
the topic level should only be made from cross references (using <code class="keyword markupname xmlelement">&lt;xref&gt;</code> or similar)
inside of a topic. For details, see the href attribute description in the OASIS standard’s definition of the
<a class="xref" href="http://docs.oasis-open.org/dita/v1.2/os/spec/langref/topicref.html" target="_blank" rel="external noopener">topicref element</a>.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">This will appear when generating PDF
or ODT output that includes a link to a local topic, but the referenced topic is not part of the map itself.
This will result in a broken link. You should include the topic in your map or remove the link from the
build.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">The copy-to attribute is used to copy
a topic over a document that already exists. Please make sure that any copy-to attributes use a unique name so
that the copy will not overwrite existing content.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">Two different topics are copied to
the same location using copy-to; as a result, one of these files would be over-written. Only the first
instance of this copy-to value will be recognized. Please correct the use of copy-to attributes.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">This message indicates that your
custom XSLT or plug-ins rely on templates that will be removed in an upcoming release. Typically this occurs
when a named template has been converted to a mode template; any code that uses the deprecated template should
be updated.</td>
</tr><tr class="strow">
<td class="stentry" headers="errormessages__stentry__1">This PDF build uses generated text,
such as the phrase "Related information" (which is generated above many link groups). The toolkit was unable
to locate the string <var class="keyword varname">%1</var> for your specified language, so the string will appear in the
default language. This generally indicates that the toolkit’s strings need to be updated to support your
language, or that your language setting is incorrect.</td>
</tr></tbody></table>
<section class="section"><h2 class="title sectiontitle">Additional explanation for messages in the <span class="ph filepath">org.dita.pdf2</span> plugin</h2>
<table class="simpletable"><colgroup><col style="width:100%"></colgroup><tbody><tr class="strow">
<td class="stentry">The PDF index process relies on
pre-defined letter headings when sorting terms. The specified term does not begin with a character that can
be mapped to an existing heading. Typically this term would be placed in a "Special characters" group, but
the current language did not specify such a group when setting up the index sort process.</td>
</tr><tr class="strow">
<td class="stentry">The PDF index process relies on
pre-defined letter headings when sorting terms. The specified term does not begin with a character that can
be mapped to an existing heading, so it has been placed under a heading for terms that begin with special
characters such as punctuation. If this term should be sorted under a new or existing letter heading, please
open an issue with DITA-OT to correct the sort.</td>
</tr><tr class="strow">
<td class="stentry">Found an
<code class="keyword markupname xmlelement">&lt;index-see&gt;</code> element as a child of a term that also exists as a standalone index
term, or as a term that also uses <code class="keyword markupname xmlelement">&lt;index-see-also&gt;</code>. When using
<code class="keyword markupname xmlelement">&lt;index-see&gt;</code> with an index term, that term should not be used to create page
references and should not reference additional terms. Treating the <code class="keyword markupname xmlelement">&lt;index-see&gt;</code> as
<code class="keyword markupname xmlelement">&lt;index-see-also&gt;</code>.</td>
</tr><tr class="strow">
<td class="stentry">
</td>
</tr></tbody></table>
</section>
</div>
</article></main></body></html>

410
dita-ot-3.6/doc/topics/error-messages.html Normal file
View file

File diff suppressed because one or more lines are too long

59
dita-ot-3.6/doc/topics/first-build-using-dita-command.html Normal file
View file

@ -0,0 +1,59 @@
<!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="You can generate output using the dita command-line tool. Build parameters can be specified on the command line or with .properties files."><meta name="keywords" content="macOS, command, dita, Linux, Windows, command, using"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Building output using the dita command</title></head><body id="using-command-line-tool"><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><ul><li><a href="../topics/prerequisite-software.html">Prerequisite software</a></li><li><a href="../topics/determining-version-of-ditaot.html">Checking the version</a></li><li class="active"><a href="../topics/first-build-using-dita-command.html">Building output</a></li><li><a href="../topics/installing-via-homebrew.html">Installing via Homebrew</a></li></ul></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></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">Building output using the <span class="keyword cmdname">dita</span> command</h1>
<div class="body taskbody"><p class="shortdesc">You can generate output using the <span class="keyword cmdname">dita</span> command-line tool. Build parameters can be
specified on the command line or with <span class="ph filepath">.properties</span> files.</p>
<section class="section context"><div class="tasklabel"><h2 class="sectiontitle tasklabel">About this task</h2></div>The DITA-OT client is a command-line tool with no graphical user interface. To verify
that your installation works correctly, you can build output using the sample files included in the distribution
package.</section>
<section><div class="tasklabel"><h2 class="sectiontitle tasklabel">Procedure</h2></div><ol class="ol steps"><li class="li step stepexpand">
<span class="ph cmd">Open a terminal window by typing the following in the search bar:</span>
<table border="1" frame="hsides" rules="rows" cellpadding="4" cellspacing="0" summary="" class="simpletable choicetable choicetableborder multi-platform"><colgroup><col style="width:25%"><col style="width:75%"></colgroup><thead><tr class="sthead chhead"><th scope="col" class="stentry choptionhd" style="vertical-align:bottom;text-align:left;">Option</th><th scope="col" class="stentry chdeschd" style="vertical-align:bottom;text-align:left;">Description</th></tr></thead><tbody><tr class="strow chrow">
<th style="vertical-align:top;" scope="row" class="stentry choption">Linux or macOS&nbsp;</th>
<td style="vertical-align:top;" class="stentry chdesc">Type <kbd class="ph userinput">Terminal</kbd>.</td>
</tr><tr class="strow chrow">
<th style="vertical-align:top;" scope="row" class="stentry choption">Windows</th>
<td style="vertical-align:top;" class="stentry chdesc">Type <kbd class="ph userinput">Command Prompt</kbd>.</td>
</tr></tbody></table>
</li><li class="li step stepexpand">
<span class="ph cmd">At the command-line prompt, enter the following command:</span>
<div class="itemgroup info"><pre class="pre codeblock syntax-bash"><code><span class="ph filepath"><span class="keyword cmdname">dita</span></span> <span class="keyword parmname">--input</span>=<var class="keyword varname">input-file</var> <span class="keyword parmname">--format</span>=<var class="keyword varname">format</var> </code></pre>
<p class="p">where:</p>
<ul class="ul">
<li class="li"><var class="keyword varname">input-file</var> is the DITA map or DITA file that you want to
process.</li><li class="li">
<p class="p" id="using-command-line-tool__d1183e251">
<var class="keyword varname">format</var> is the output format (transformation type). This argument corresponds to the
common parameter <span class="keyword parmname">transtype</span>. Use the same values as for the
<span class="keyword parmname">transtype</span> build parameter, for example <span class="keyword option">html5</span> or
<span class="keyword option">pdf</span>.</p>
</li>
</ul></div>
<div class="itemgroup stepresult">
<p class="p">If processing is successful, nothing is printed in the terminal window. The built output is written to the
specified output directory (by default, in the <span class="ph filepath">out</span> subdirectory of the current
directory).</p>
</div>
</li></ol></section>
<section class="example"><div class="tasklabel"><h2 class="sectiontitle tasklabel">Example</h2></div>
<p class="p">Run from <span class="ph filepath"><var class="keyword varname">dita-ot-dir</var>/docsrc/samples</span>, the following command generates HTML5 output for the
<span class="ph filepath">sequence.ditamap</span> file:</p>
<pre class="pre codeblock"><code><span class="ph filepath"><span class="keyword cmdname">dita</span></span> <span class="keyword parmname">--input</span>=<span class="ph filepath">sequence.ditamap</span> <span class="keyword parmname">--format</span>=<span class="keyword option">html5</span></code></pre>
</section>
<section class="section postreq"><div class="tasklabel"><h2 class="sectiontitle tasklabel">What to do next</h2></div>
<p class="p">Most builds require you to specify more options than are described in this topic.</p>
</section>
</div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/installing-client.html" title="The DITA-OT distribution package can be installed on Linux, macOS, and Windows. It contains everything that you need to run the toolkit except for Java.">Installing DITA Open Toolkit</a></div></div><div class="linklist reltasks"><strong>Related tasks</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/build-using-dita-command.html" title="You can generate output using the dita command-line tool. Build parameters can be specified on the command line or with .properties files.">More information about building output with the <span class="keyword cmdname">dita</span> command</a></li></ul></div></nav></article></main></body></html>

267
dita-ot-3.6/doc/topics/globalization-languages.html Normal file
View file

@ -0,0 +1,267 @@
<!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="The following languages are supported for all PDF, XHTML, and HTML5-based transformation types."><meta name="keywords" content=", xml:lang, Arabic, Bosnian, Belarusian, Bulgarian, Catalan, Chinese, Croatian, Czech, Danish, Dutch, English, Estonian, Finnish, French, German, Greek, Hebrew, Hungarian, Hindi, Icelandic, Indonesian, Italian, Japanese, Kazakh, Korean, Latvian, Lithuanian, Malay, Montenegrin, Norwegian, Polish, Portuguese, Romanian, Russian, Serbian, Slovak, Slovenian, Spanish, Swedish, Thai, Turkish, Ukrainian, Urdu, Vietnamese, languages, supported, list of, language codes, strings, generated text, index, sorting"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Supported languages</title></head><body id="dita-globalization-languages"><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><ul><li><a href="../topics/globalization-support.html">Globalization support</a></li><li><a href="../topics/plugin-addgeneratedtext.html">Customizing generated text</a></li><li class="active"><a href="../topics/globalization-languages.html">Supported languages</a></li></ul></li><li><a href="../topics/migration.html">Migrating customizations</a></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">Supported languages</h1>
<div class="body refbody"><p class="shortdesc">The following languages are supported for all PDF, XHTML, and HTML5-based transformation types.</p>
<section class="section refsyn">
<div class="note note note_note"><span class="note__title">Note:</span> While language codes listed below use the conventional capitalization style of "aa-BB" and "aa-Script-BB",
DITA-OT processing is not case sensitive when reading these values from the <code class="keyword markupname xmlatt">@xml:lang</code>
attribute.</div>
</section>
<table class="table table-hover frame-none"><caption><span class="table--title-label">Table 1. </span><span class="title">Supported languages</span></caption><colgroup><col style="width:30%"><col style="width:20%"><col style="width:50%"></colgroup><thead class="thead">
<tr class="row">
<th class="entry colsep-0 rowsep-1" id="dita-globalization-languages__entry__1">Language</th>
<th class="entry colsep-0 rowsep-1" id="dita-globalization-languages__entry__2">Language&nbsp;code</th>
<th class="entry colsep-0 rowsep-1" id="dita-globalization-languages__entry__3">Notes</th>
</tr>
</thead><tbody class="tbody">
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__1"><span lang="ar" class="ph">العربية</span> (Arabic)</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__2">ar or ar-EG</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__3">Defaults to right-to-left presentation.</td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__1"><span lang="be" class="ph">Беларуская</span> (Belarusian)</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__2">be or be-BY</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__3"></td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__1"><span lang="bs" class="ph">Bosanski</span> (Bosnian)</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__2">bs or bs-BA</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__3"></td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__1"><span lang="bg" class="ph">Български</span> (Bulgarian)</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__2">bg or bg-BG</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__3"></td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__1"><span lang="ca" class="ph">Català</span> (Catalan)</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__2">ca-ES</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__3"></td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__1"><span lang="zh-CN" class="ph">简体中文</span> (Simplified Chinese)</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__2">zh-CN or zh-Hans</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__3">PDF index is not properly collated by default.</td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__1"><span lang="zh-TW" class="ph">繁體中文</span> (Traditional Chinese)</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__2">zh-TW or zh-Hant</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__3">PDF index is not properly collated by default.</td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__1"><span lang="hr" class="ph">Hrvatski</span> (Croatian)</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__2">hr or hr-HR</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__3"></td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__1"><span lang="cs" class="ph">Čeština</span> (Czech)</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__2">cs or cs-CZ</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__3"></td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__1"><span lang="da" class="ph">Dansk</span> (Danish)</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__2">da or da-DK</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__3"></td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__1"><span lang="nl" class="ph">Nederlands</span> (Dutch)</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__2">nl or nl-NL</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__3">Subset of generated text also available for Belgian Dutch (nl-BE)</td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__1">English (US)</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__2">en or en-US</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__3">Subset of generated text also available for British English (en-GB) and Canadian English
(en-CA)</td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__1"><span lang="et" class="ph">Eesti</span> (Estonian)</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__2">et or et-EE</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__3"></td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__1"><span lang="fi" class="ph">Suomi</span> (Finnish)</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__2">fi or fi-FI</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__3"></td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__1"><span lang="fr" class="ph">Français</span> (French)</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__2">fr or fr-FR</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__3">Subset of generated text also available for Belgian French (fr-BE), Canadian French (fr-CA), and
Swiss French (fr-CH)</td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__1"><span lang="de" class="ph">Deutsch</span> (German)</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__2">de or de-DE</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__3">Subset of generated text also available for Swiss German (de-CH)</td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__1"><span lang="el" class="ph">Ελληνικά</span> (Greek)</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__2">el or el-GR</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__3"></td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__1"><span lang="he" class="ph">עברית</span> (Hebrew)</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__2">he or he-IL</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__3">Defaults to right-to-left presentation.</td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__1"><span lang="hi" class="ph">हिन्दी</span> (Hindi)</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__2">hi or hi-HI</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__3"></td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__1"><span lang="hu" class="ph">Magyar</span> (Hungarian)</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__2">hu or hu-HU</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__3"></td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__1"><span lang="is" class="ph">Íslenska</span> (Icelandic)</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__2">is or is-IS</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__3"></td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__1"><span lang="id" class="ph">Bahasa Indonesia</span> (Indonesian)</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__2">id or id-ID</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__3"></td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__1"><span lang="it" class="ph">Italiano</span> (Italian)</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__2">it or it-IT</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__3">Subset of generated text also available for Swiss Italian (it-CH)</td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__1"><span lang="ja" class="ph">日本語</span> (Japanese)</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__2">ja or ja-JP</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__3">PDF index is not properly collated by default.</td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__1"><span lang="kk" class="ph">Қазақша</span> (Kazakh)</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__2">kk or kk-KZ</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__3"></td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__1"><span lang="ko" class="ph">한국어</span> (Korean)</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__2">ko or ko-KR</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__3"></td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__1"><span lang="lv" class="ph">Latviešu</span> (Latvian)</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__2">lv or lv-LV</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__3"></td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__1"><span lang="lt" class="ph">Lietuvių</span> (Lithuanian)</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__2">lt or lt-LT</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__3"></td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__1"><span lang="mk" class="ph">Македонски</span> (Macedonian)</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__2">mk or mk-MK</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__3"></td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__1"><span lang="ms" class="ph">Bahasa Melayu</span> (Malay)</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__2">ms or ms-MY</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__3"></td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__1"><span lang="sr-Latn-ME" class="ph">Crnogorski</span> (Montenegrin)</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__2">sr-Latn-ME</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__3"></td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__1"><span lang="no" class="ph">Norsk</span> (Norwegian)</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__2">no or no-NO</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__3"></td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__1"><span lang="pl" class="ph">Polski</span> (Polish)</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__2">pl or pl-PL</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__3"></td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__1"><span lang="pt" class="ph">Português</span> (Portuguese)</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__2">pt or pt-PT</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__3"></td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__1"><span lang="pt-BR" class="ph">Português do Brasil</span> (Brazilian Portuguese)</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__2">pt-BR</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__3"></td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__1"><span lang="ro" class="ph">Română</span> (Romanian)</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__2">ro or ro-RO</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__3"></td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__1"><span lang="ru" class="ph">Русский</span> (Russian)</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__2">ru or ru-RU</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__3"></td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__1"><span lang="sr" class="ph">Српски</span> (Serbian - Cyrillic script)</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__2">sr, sr-CS, sr-RS, or sr-SP</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__3"></td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__1"><span lang="sr-Latn-RS" class="ph">Srpski</span> (Serbian - Latin script)</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__2">sr-Latn-RS</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__3"></td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__1"><span lang="sk" class="ph">Slovenčina</span> (Slovak)</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__2">sk or sk-SK</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__3"></td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__1"><span lang="sl" class="ph">Slovenščina</span> (Slovenian)</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__2">sl or sl-SI</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__3"></td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__1"><span lang="es" class="ph">Español</span> (Spanish)</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__2">es or es-ES</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__3">Also supported using es-419 (Latin American Spanish).</td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__1"><span lang="sv" class="ph">Svenska</span> (Swedish)</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__2">sv or sv-SE</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__3"></td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__1"><span lang="th" class="ph">ภาษาไทย</span> (Thai)</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__2">th or th-TH</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__3"></td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__1"><span lang="tr" class="ph">Türkçe</span> (Turkish)</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__2">tr or tr-TR</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__3"></td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__1"><span lang="uk" class="ph">Українська</span> (Ukrainian)</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__2">uk or uk-UA</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__3"></td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__1"><span lang="ur" class="ph">اردو</span> (Urdu)</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__2">ur or ur-PK</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__3">Defaults to right-to-left presentation.</td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__1"><span lang="vi" class="ph">Tiếng Việt</span> (Vietnamese)</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__2">vi or vi-VN</td>
<td class="entry colsep-0 rowsep-1" headers="dita-globalization-languages__entry__3"></td>
</tr>
</tbody></table>
</div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/globalization.html" title="The DITA standard supports content that is written in or translated to any language. In general, DITA Open Toolkit passes content through to the output format unchanged. DITA-OT uses the values for the xml:lang and dir attributes that are set in the source content to provide globalization support. You can create custom plug-ins to support additional languages.">Globalizing DITA content</a></div></div><div class="linklist relref"><strong>Related reference</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/plugin-addgeneratedtext.html" title="Generated text is the term for strings that are automatically added by the build, such as &#34;Note&#34; before the contents of a note element.">How to add support for new languages in HTML</a></li></ul></div></nav></article></main></body></html>

41
dita-ot-3.6/doc/topics/globalization-support.html Normal file
View file

@ -0,0 +1,41 @@
<!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 Open Toolkit offers globalization support in the following areas: generated text, index sorting, and bi-directional text."><meta name="keywords" content=", dir, index:lang, languages, index sorting, right-to-left, bi-directional, English, strings, index, sorting, bi-directional languages, generated text, CSS, right-to-left languages"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Globalization support</title></head><body id="globalization-support"><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><ul><li class="active"><a href="../topics/globalization-support.html">Globalization support</a></li><li><a href="../topics/plugin-addgeneratedtext.html">Customizing generated text</a></li><li><a href="../topics/globalization-languages.html">Supported languages</a></li></ul></li><li><a href="../topics/migration.html">Migrating customizations</a></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">Globalization support</h1>
<div class="body conbody"><p class="shortdesc">DITA Open Toolkit offers globalization support in the following areas: generated text, index sorting, and
bi-directional text.</p>
<div class="p">
<dl class="dl">
<dt class="dt dlterm">Generated text</dt>
<dd class="dd"><dfn class="term">Generated text</dfn> is text that is rendered automatically in the output that is generated by
DITA-OT; this text is not located in the DITA source files. The following are examples of generated text:
<ul class="ul">
<li class="li">The word "Chapter" in a PDF file.</li>
<li class="li">The phrases "Related concepts," "Related tasks," and "Related reference" in HTML output.</li>
</ul></dd>
<dt class="dt dlterm">Index sorting</dt>
<dd class="dd">DITA-OT can use only a single language to sort indexes.</dd>
<dt class="dt dlterm">Bi-directional text</dt>
<dd class="dd">DITA-OT contains style sheets (CSS files) that support both left-to-right (LTR) and right-to-left (RTL)
languages in HTML based transformations. PDF supports both LTR and RTL rendering based on the document
language. The <code class="keyword markupname xmlatt">@dir</code> attribute can be used to override the default rendering direction.</dd>
</dl>When DITA-OT generates output, it takes the first value for the <code class="keyword markupname xmlatt">@xml:lang</code> attribute that it
encounters, and then it uses that value to create generated text, perform index sorting, and determine which
default CSS file is used. If no value for the <code class="keyword markupname xmlatt">@xml:lang</code> attribute is found, the toolkit defaults
to U.S. English. You can use the
<a class="xref" href="../parameters/configuration-properties.html" title="DITA-OT uses .properties files and internal properties that store configuration settings for the toolkit and its plug-ins. Configuration properties are available to both Ant and Java processes, but unlike argument properties, they cannot be set at run time.">configuration.properties</a> to change the default
language.</div>
</div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/globalization.html" title="The DITA standard supports content that is written in or translated to any language. In general, DITA Open Toolkit passes content through to the output format unchanged. DITA-OT uses the values for the xml:lang and dir attributes that are set in the source content to provide globalization support. You can create custom plug-ins to support additional languages.">Globalizing DITA content</a></div></div></nav></article></main></body></html>

13
dita-ot-3.6/doc/topics/globalization.html Normal file
View file

@ -0,0 +1,13 @@
<!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="The DITA standard supports content that is written in or translated to any language. In general, DITA Open Toolkit passes content through to the output format unchanged. DITA-OT uses the values for the xml:lang and dir attributes that are set in the source content to provide globalization support. You can create custom plug-ins to support additional languages."><meta name="keywords" content=", dir, index:lang, languages, supported, translating, localizing, globalizing, strings"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Globalizing DITA content</title></head><body id="dita-globalization"><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 class="active"><a href="../topics/globalization.html">Globalizing DITA content</a><ul><li><a href="../topics/globalization-support.html">Globalization support</a></li><li><a href="../topics/plugin-addgeneratedtext.html">Customizing generated text</a></li><li><a href="../topics/globalization-languages.html">Supported languages</a></li></ul></li><li><a href="../topics/migration.html">Migrating customizations</a></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">Globalizing DITA content</h1>
<p class="shortdesc">The DITA standard supports content that is written in or translated to any language. In general, DITA Open
Toolkit passes content through to the output format unchanged. DITA-OT uses the values for the
<code class="keyword markupname xmlatt">@xml:lang</code> and <code class="keyword markupname xmlatt">@dir</code> attributes that are set in the source content to provide
globalization support. You can create custom plug-ins to support additional languages.</p>
<nav role="navigation" class="related-links"><ul class="ullinks"><li class="link ulchildlink"><strong><a href="../topics/globalization-support.html">Globalization support</a></strong><br>DITA Open Toolkit offers globalization support in the following areas: generated text, index sorting, and bi-directional text.</li><li class="link ulchildlink"><strong><a href="../topics/plugin-addgeneratedtext.html">Customizing generated text</a></strong><br>Generated text is the term for strings that are automatically added by the build, such as "Note" before the contents of a <code class="keyword markupname xmlelement">&lt;note&gt;</code> element.</li><li class="link ulchildlink"><strong><a href="../topics/globalization-languages.html">Supported languages</a></strong><br>The following languages are supported for all PDF, XHTML, and HTML5-based transformation types.</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 relref"><strong>Related reference</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="http://docs.oasis-open.org/dita/v1.2/os/spec/archSpec/translation.html" target="_blank" rel="external noopener">Localization overview in the OASIS DITA standard</a></li></ul></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/2017/dita-ot_day.html#Open_Toolkit" target="_blank" rel="external noopener" title="Presents the DITA Community i18n Plugin, which provides an integration with the ICU4J libraries. The i18n plugin provides support for locale-specific grouping and sorting, including dictionary-based Simplified Chinese, as well as facilities for doing locale-specific word and line breaking.">Locale-Aware Sorting and Text Handling in the Open Toolkit</a></li><li class="linklist"><a class="link" href="https://www.oxygenxml.com/events/2016/dita-ot_day.html#DITA-OT_Who_does_what" target="_blank" rel="external noopener" title="While tools can be used to simplify many things, localization can still be scary. In this session, we'll go over how the toolkit is set up to handle publishing in multiple languages: what comes out of the box? What should you expect to do on your own? And how has this changed over the last few releases? Also: stories of panic from the past!">Internationalization and the DITA-OT: Who does what?</a></li></ul></div></nav></article></main></body></html>

50
dita-ot-3.6/doc/topics/html-customization-css.html Normal file
View file

@ -0,0 +1,50 @@
<!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="To modify the appearance of the default HTML output that DITA Open Toolkit generates, you can reference a custom Cascading Style Sheet (CSS) file with the typography, colors, and other presentation aspects that define your corporate identity."><meta name="keywords" content="cascading style sheet, CSS, CSS, adding custom, HTML, HTML5, transformations, HTML5"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Adding custom CSS</title></head><body id="custom-html-css"><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><ul><li><a href="../topics/html-customization-parameters.html">Setting HTML parameters</a><ul><li><a href="../topics/html-customization-navigation.html">Adding navigation</a></li><li class="active"><a href="../topics/html-customization-css.html">Adding custom CSS</a></li><li><a href="../topics/html-customization-header.html">Headers and footers</a></li><li><a href="../parameters/generate-copy-outer.html">Handling content outside the map directory</a></li></ul></li><li><a href="../topics/html-customization-properties-file.html">Using a properties file</a></li></ul></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></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">Adding custom CSS</h1>
<div class="body taskbody"><p class="shortdesc">To modify the appearance of the default HTML output that DITA Open Toolkit generates, you can reference a
custom Cascading Style Sheet (CSS) file with the typography, colors, and other presentation aspects that define your
corporate identity.</p>
<section class="section context"><div class="tasklabel"><h2 class="sectiontitle tasklabel">About this task</h2></div>
<p class="p">You can use this approach when you need to adjust the look and feel of the default output for a single project,
but don’t want to create a custom DITA-OT plug-in.</p>
<p class="p">You can version the CSS file along with the DITA source files in your project, so stylesheet changes can be
tracked along with modifications to topic content.</p>
<p class="p">You may also find this approach useful as you develop a custom stylesheet. Once the CSS rules stabilize, you
can bundle the CSS file in a custom DITA-OT plug-in to ensure consistent HTML output across
projects.</p></section>
<section><div class="tasklabel"><h2 class="sectiontitle tasklabel">Procedure</h2></div><ol class="ol steps"><li class="li step stepexpand">
<span class="ph cmd">Create a custom CSS file and store it in your project along with your DITA source files.</span>
<div class="itemgroup stepxmp">
<div class="note note note_note"><span class="note__title">Note:</span> As a starting point, you can use the CSS file that is used for the DITA-OT documentation. This file is
available in the installation folder under <span class="ph filepath">docsrc/resources/dita-ot-doc.css</span>.</div>
</div>
</li><li class="li step stepexpand">
<span class="ph cmd">Set the <span class="keyword parmname">args.css</span> parameter to the name of your custom CSS file.</span>
<div class="itemgroup info">
<p class="p">The value of this parameter should be only the file name. You can specify the absolute path to the file
with <span class="keyword parmname">args.cssroot</span>.</p></div>
</li><li class="li step stepexpand">
<span class="ph cmd">Set the <span class="keyword parmname">args.copycss</span> parameter to <span class="keyword option">yes</span>.</span>
<div class="itemgroup info">
<p class="p">This setting ensures that your custom CSS file will be copied to the output directory.</p></div>
</li><li class="li step stepexpand">
<span class="ph cmd">Set <span class="keyword parmname">args.cssroot</span> to the absolute path of the folder that contains your custom CSS file.</span>
</li><li class="li step stepexpand"><strong>Optional: </strong>
<span class="ph cmd">Set <span class="keyword parmname">args.csspath</span> to specify the location of the CSS file in the output folder.</span>
<div class="itemgroup info">
<p class="p">If <span class="keyword parmname">args.csspath</span> is not set, the custom CSS file will be copied to the root level of
the output folder. To copy the CSS file to a subfolder named <span class="ph filepath">css</span>, set
<span class="keyword parmname">args.csspath</span> to <span class="keyword option">css</span>.</p></div>
</li></ol></section>
<section class="section result"><div class="tasklabel"><h2 class="sectiontitle tasklabel">Results</h2></div>
<div class="note tip note_tip"><span class="note__title">Tip:</span> For an example of HTML output generated using this method, see the HTML5 version of the DITA-OT
documentation included in the installation folder under <span class="ph filepath">doc/index.html</span>.</div>
</section>
</div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/html-customization-parameters.html" title="For simple branded HTML pages, you can adjust the look and feel of the default output to match your company style by setting parameters to include custom CSS, header branding, or table-of-contents navigation in topics. (These changes do not require a custom plug-in.)">Setting parameters for custom HTML</a></div></div><div class="linklist relconcepts"><strong>Related concepts</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../parameters/generate-copy-outer.html" title="By default, DITA-OT assumes content is located in or beneath the directory containing the DITA map file. The generate.copy.outer parameter can be used to adjust how output is generated for content that is located outside the map directory.">Handling content outside the map directory</a></li></ul></div><div class="linklist reltasks"><strong>Related tasks</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/html-customization-navigation.html" title="In HTML5 output, you can set a parameter to include table-of-contents navigation in the nav element of each page. The navigation can be rendered in a sidebar or menu via CSS.">Adding navigation to topics</a></li><li class="linklist"><a class="link" href="../topics/html-customization-header.html" title="You add a custom header to include a publication title, company logo, or other common branding elements in HTML output. A custom footer can also be added with copyright information, legal boilerplate, or other fine print.">Adding custom headers and footers</a></li><li class="linklist"><a class="link" href="../topics/html-customization-plugin-bundle-css.html" title="You can create a DITA-OT plug-in that provides a custom stylesheet with the typography and colors that define your corporate identity. Coworkers can install this plug-in to ensure consistent HTML output across projects without having to copy the stylesheet to each project.">Bundling CSS in a custom HTML plug-in</a></li></ul></div></nav></article></main></body></html>

66
dita-ot-3.6/doc/topics/html-customization-header.html Normal file
View file

@ -0,0 +1,66 @@
<!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="You add a custom header to include a publication title, company logo, or other common branding elements in HTML output. A custom footer can also be added with copyright information, legal boilerplate, or other fine print."><meta name="keywords" content=", header, footer, , div, HTML header, HTML footer, role, HTML5, headers, footers, CSS, adding custom, HTML5, CSS"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Adding custom headers and footers</title></head><body id="custom-html-header"><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><ul><li><a href="../topics/html-customization-parameters.html">Setting HTML parameters</a><ul><li><a href="../topics/html-customization-navigation.html">Adding navigation</a></li><li><a href="../topics/html-customization-css.html">Adding custom CSS</a></li><li class="active"><a href="../topics/html-customization-header.html">Headers and footers</a></li><li><a href="../parameters/generate-copy-outer.html">Handling content outside the map directory</a></li></ul></li><li><a href="../topics/html-customization-properties-file.html">Using a properties file</a></li></ul></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></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">Adding custom headers and footers</h1>
<div class="body taskbody"><p class="shortdesc">You add a custom header to include a publication title, company logo, or other common branding elements in
HTML output. A custom footer can also be added with copyright information, legal boilerplate, or other fine
print.</p>
<section class="section context"><div class="tasklabel"><h2 class="sectiontitle tasklabel">About this task</h2></div>
<p class="p">In HTML5 output, the contents of the header file will be wrapped in an HTML5 <code class="keyword markupname xmlelement">&lt;header&gt;</code>
element with the <code class="keyword markupname xmlatt">@role</code> attribute set to <span class="keyword option">banner</span>. The footer file contents are
wrapped in an HTML5 <code class="keyword markupname xmlelement">&lt;footer&gt;</code> element with the <code class="keyword markupname xmlatt">@role</code> attribute set to
<span class="keyword option">contentinfo</span>.</p>
<p class="p">For example, the DITA-OT documentation includes a simple header banner with the publication title and a
horizontal rule to separate the header from the generated topic content: </p>
<div class="p"><pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;div class="header"&gt;
&lt;p&gt;DITA Open Toolkit&lt;/p&gt;
&lt;hr/&gt;
&lt;/div&gt;</code></pre>
</div>
<div class="note note note_note"><span class="note__title">Note:</span> Header and footer files should be specified using absolute paths and must contain valid XML. A common
practice is to place all content into a <code class="keyword markupname xmlelement">&lt;div&gt;</code> element.</div>
</section>
<section><div class="tasklabel"><h2 class="sectiontitle tasklabel">Procedure</h2></div><ol class="ol steps"><li class="li step stepexpand">
<span class="ph cmd">Set <span class="keyword parmname">args.hdr</span> to include an XML file as a running header that appears above the page
content.</span>
<div class="itemgroup info"> </div>
</li><li class="li step stepexpand">
<span class="ph cmd">Set <span class="keyword parmname">args.ftr</span> to include an XML file as a running footer that appears below the page
content.</span>
</li><li class="li step stepexpand"><strong>Optional: </strong>
<span class="ph cmd">Add custom CSS rules to style headers and/or footers.</span>
<div class="itemgroup info">
<p class="p">For example, the DITA-OT documentation stylesheet includes the following header rules: </p>
<div class="p"><pre class="pre codeblock language-css normalize-space show-line-numbers show-whitespace"><code>.header {
font-size: 18pt;
margin: 0;
padding: 0 12px;
}
.header p {
color: #1d365d;
font-family: 'Helvetica Neue', Helvetica, Arial, sans-serif;
line-height: 1.3;
margin: 0;
}
.header hr {
border: 0;
border-bottom: 1px solid #eee;
height: 0;
}</code></pre>
</div>
</div>
</li></ol></section>
<section class="section result"><div class="tasklabel"><h2 class="sectiontitle tasklabel">Results</h2></div>
<div class="note tip note_tip"><span class="note__title">Tip:</span> For an example of HTML output generated using this method, see the HTML5 version of the DITA-OT
documentation included in the installation folder under <span class="ph filepath">doc/index.html</span>.</div>
</section>
</div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/html-customization-parameters.html" title="For simple branded HTML pages, you can adjust the look and feel of the default output to match your company style by setting parameters to include custom CSS, header branding, or table-of-contents navigation in topics. (These changes do not require a custom plug-in.)">Setting parameters for custom HTML</a></div></div><div class="linklist relconcepts"><strong>Related concepts</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../parameters/generate-copy-outer.html" title="By default, DITA-OT assumes content is located in or beneath the directory containing the DITA map file. The generate.copy.outer parameter can be used to adjust how output is generated for content that is located outside the map directory.">Handling content outside the map directory</a></li></ul></div><div class="linklist reltasks"><strong>Related tasks</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/html-customization-navigation.html" title="In HTML5 output, you can set a parameter to include table-of-contents navigation in the nav element of each page. The navigation can be rendered in a sidebar or menu via CSS.">Adding navigation to topics</a></li><li class="linklist"><a class="link" href="../topics/html-customization-css.html" title="To modify the appearance of the default HTML output that DITA Open Toolkit generates, you can reference a custom Cascading Style Sheet (CSS) file with the typography, colors, and other presentation aspects that define your corporate identity.">Adding custom CSS</a></li></ul></div></nav></article></main></body></html>

50
dita-ot-3.6/doc/topics/html-customization-navigation.html Normal file
View file

@ -0,0 +1,50 @@
<!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="In HTML5 output, you can set a parameter to include table-of-contents navigation in the nav element of each page. The navigation can be rendered in a sidebar or menu via CSS."><meta name="keywords" content=", nav, HTML5, navigation, adding, transformations, HTML5, CSS, adding custom, nav-toc, table of contents"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Adding navigation to topics</title></head><body id="custom-html-navigation"><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><ul><li><a href="../topics/html-customization-parameters.html">Setting HTML parameters</a><ul><li class="active"><a href="../topics/html-customization-navigation.html">Adding navigation</a></li><li><a href="../topics/html-customization-css.html">Adding custom CSS</a></li><li><a href="../topics/html-customization-header.html">Headers and footers</a></li><li><a href="../parameters/generate-copy-outer.html">Handling content outside the map directory</a></li></ul></li><li><a href="../topics/html-customization-properties-file.html">Using a properties file</a></li></ul></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></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">Adding navigation to topics</h1>
<div class="body taskbody"><p class="shortdesc">In HTML5 output, you can set a parameter to include table-of-contents navigation in the
<code class="keyword markupname xmlelement">&lt;nav&gt;</code> element of each page. The navigation can be rendered in a sidebar or menu via
CSS.</p>
<section class="section context"><div class="tasklabel"><h2 class="sectiontitle tasklabel">About this task</h2></div>
<p class="p">Earlier versions of DITA-OT used the TocJS transformation to render a JavaScript-based table of contents in an
XHTML frameset for topic navigation. Recent toolkit versions provide a modern HTML5 navigation alternative.</p>
<p class="p">As of DITA-OT 2.2, the <span class="keyword parmname">nav-toc</span> parameter can be used in HTML5 transformations to embed
navigation directly in topics using native HTML5 elements without JavaScript or framesets.</p>
</section>
<section><div class="tasklabel"><h2 class="sectiontitle tasklabel">Procedure</h2></div><ol class="ol steps"><li class="li step stepexpand">
<span class="ph cmd">Set the <span class="keyword parmname">nav-toc</span> parameter to one of the following options:</span>
<ul class="ul choices">
<li class="li choice">The <span class="keyword option">partial</span> option creates a table of contents with the portion of the navigation
hierarchy that contains the current topic (along with its parents, siblings and children).</li>
<li class="li choice">The <span class="keyword option">full</span> option embeds the complete navigation for the entire map in each
topic.</li>
</ul>
</li><li class="li step stepexpand"><strong>Optional: </strong>
<span class="ph cmd">Add custom CSS rules to style the navigation.</span>
<div class="itemgroup info">
<p class="p">For example, the DITA-OT documentation stylesheet includes the following rules to place the table of
contents on the left side of the browser viewport and highlight the current topic in bold:</p>
<div class="p">
<pre class="pre codeblock language-css normalize-space show-line-numbers show-whitespace"><code>nav[role='toc'] {
float: left;
width: 300px;
}
nav[role='toc'] li.active &gt; a {
font-weight: bold;
}</code></pre>
</div>
</div>
</li></ol></section>
<section class="section result"><div class="tasklabel"><h2 class="sectiontitle tasklabel">Results</h2></div>
<div class="note tip note_tip"><span class="note__title">Tip:</span> For an example of HTML output generated using this method, see the HTML5 version of the DITA-OT
documentation included in the installation folder under <span class="ph filepath">doc/index.html</span>.</div>
</section>
</div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/html-customization-parameters.html" title="For simple branded HTML pages, you can adjust the look and feel of the default output to match your company style by setting parameters to include custom CSS, header branding, or table-of-contents navigation in topics. (These changes do not require a custom plug-in.)">Setting parameters for custom HTML</a></div></div><div class="linklist relconcepts"><strong>Related concepts</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../parameters/generate-copy-outer.html" title="By default, DITA-OT assumes content is located in or beneath the directory containing the DITA map file. The generate.copy.outer parameter can be used to adjust how output is generated for content that is located outside the map directory.">Handling content outside the map directory</a></li></ul></div><div class="linklist reltasks"><strong>Related tasks</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/html-customization-css.html" title="To modify the appearance of the default HTML output that DITA Open Toolkit generates, you can reference a custom Cascading Style Sheet (CSS) file with the typography, colors, and other presentation aspects that define your corporate identity.">Adding custom CSS</a></li><li class="linklist"><a class="link" href="../topics/html-customization-header.html" title="You add a custom header to include a publication title, company logo, or other common branding elements in HTML output. A custom footer can also be added with copyright information, legal boilerplate, or other fine print.">Adding custom headers and footers</a></li></ul></div></nav></article></main></body></html>

13
dita-ot-3.6/doc/topics/html-customization-parameters.html Normal file
View file

@ -0,0 +1,13 @@
<!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="For simple branded HTML pages, you can adjust the look and feel of the default output to match your company style by setting parameters to include custom CSS, header branding, or table-of-contents navigation in topics. (These changes do not require a custom plug-in.)"><meta name="keywords" content="HTML, parameters"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Setting parameters for custom HTML</title></head><body id="custom-html-parameters"><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><ul><li class="active"><a href="../topics/html-customization-parameters.html">Setting HTML parameters</a><ul><li><a href="../topics/html-customization-navigation.html">Adding navigation</a></li><li><a href="../topics/html-customization-css.html">Adding custom CSS</a></li><li><a href="../topics/html-customization-header.html">Headers and footers</a></li><li><a href="../parameters/generate-copy-outer.html">Handling content outside the map directory</a></li></ul></li><li><a href="../topics/html-customization-properties-file.html">Using a properties file</a></li></ul></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></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">Setting parameters for custom HTML</h1>
<p class="shortdesc">For simple branded HTML pages, you can adjust the look and feel of the default output to match your company
style by setting parameters to include custom CSS, header branding, or table-of-contents navigation in topics.
(These changes do not require a custom plug-in.)</p>
<nav role="navigation" class="related-links"><ul class="ullinks"><li class="link ulchildlink"><strong><a href="../topics/html-customization-navigation.html">Adding navigation to topics</a></strong><br>In HTML5 output, you can set a parameter to include table-of-contents navigation in the <code class="keyword markupname xmlelement">&lt;nav&gt;</code> element of each page. The navigation can be rendered in a sidebar or menu via CSS.</li><li class="link ulchildlink"><strong><a href="../topics/html-customization-css.html">Adding custom CSS</a></strong><br>To modify the appearance of the default HTML output that DITA Open Toolkit generates, you can reference a custom Cascading Style Sheet (CSS) file with the typography, colors, and other presentation aspects that define your corporate identity.</li><li class="link ulchildlink"><strong><a href="../topics/html-customization-header.html">Adding custom headers and footers</a></strong><br>You add a custom header to include a publication title, company logo, or other common branding elements in HTML output. A custom footer can also be added with copyright information, legal boilerplate, or other fine print.</li><li class="link ulchildlink"><strong><a href="../parameters/generate-copy-outer.html">Handling content outside the map directory</a></strong><br>By default, DITA-OT assumes content is located in or beneath the directory containing the DITA map file. The <span class="keyword parmname">generate.copy.outer</span> parameter can be used to adjust how output is generated for content that is located outside the map directory.</li></ul><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/html-customization.html" title="You can modify the look and feel of your HTML output by changing parameter settings to include custom CSS, headers and footers, or table-of-contents navigation in topics.">Customizing HTML output</a></div></div><div class="linklist relconcepts"><strong>Related concepts</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/dita2xhtml.html" title="The xhtml transformation generates XHTML output and a table of contents (TOC) file. This was the first transformation created for DITA Open Toolkit, and originally served as the basis for all HTML-based transformations.">XHTML transformation</a></li><li class="linklist"><a class="link" href="../topics/dita2html5.html" title="The html5 transformation generates HTML5 output and a table of contents (TOC) file.">HTML5 transformation</a></li></ul></div><div class="linklist reltasks"><strong>Related tasks</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/html-customization-properties-file.html" title="You can also use a .properties file to reference a set of build parameters when building output with the dita command. The DITA-OT documentation uses a .properties file to include custom CSS, header branding, and table-of-contents navigation in the HTML5 output.">Customizing HTML with a .properties file</a></li></ul></div><div class="linklist relref"><strong>Related reference</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../parameters/parameters-base.html" title="Certain parameters apply to all transformations that DITA Open Toolkit supports.">Common parameters</a></li><li class="linklist"><a class="link" href="../parameters/parameters-base-html.html" title="Certain parameters apply to all HTML-based transformation types: HTML5, XHTML, HTML&nbsp;Help, and Eclipse help.">HTML-based output parameters</a></li><li class="linklist"><a class="link" href="../parameters/parameters-xhtml.html" title="Certain parameters are specific to the XHTML transformation.">XHTML parameters</a></li><li class="linklist"><a class="link" href="../parameters/parameters-html5.html" title="The HTML5 transformation shares common parameters with other HTML-based transformations and provides additional parameters that are specific to HTML5 output.">HTML5 parameters</a></li></ul></div></nav></article></main></body></html>

127
dita-ot-3.6/doc/topics/html-customization-plugin-bundle-css.html Normal file
View file

@ -0,0 +1,127 @@
<!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="You can create a DITA-OT plug-in that provides a custom stylesheet with the typography and colors that define your corporate identity. Coworkers can install this plug-in to ensure consistent HTML output across projects without having to copy the stylesheet to each project."><meta name="keywords" content=", require, HTML, custom plug-in, CSS, CSS, HTML transforms"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Bundling CSS in a custom HTML plug-in</title></head><body id="custom-html-plugin-bundle-css"><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><ul><li class="active"><a href="../topics/html-customization-plugin-bundle-css.html">Bundling custom CSS</a></li><li><a href="../topics/html-customization-plugin-webfont.html">Embedding web fonts</a></li><li><a href="../topics/html-customization-plugin-javascript.html">Inserting JavaScript</a></li></ul></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></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">Bundling CSS in a custom HTML plug-in</h1>
<div class="body taskbody"><p class="shortdesc">You can create a DITA-OT plug-in that provides a custom stylesheet with the typography and colors that
define your corporate identity. Coworkers can install this plug-in to ensure consistent HTML output across projects
without having to copy the stylesheet to each project.</p>
<section class="section context"><div class="tasklabel"><h2 class="sectiontitle tasklabel">About this task</h2></div>
<p class="p">This scenario walks through the process of creating a very simple plug-in
(<code class="ph codeph">com.example.html5-custom-css</code>) that creates a new transformation type:
<span class="keyword option">html5-custom-css</span>. </p>
<p class="p">The <span class="keyword option">html5-custom-css</span> transformation includes a custom CSS file and sets four parameters to
integrate the custom stylesheet in the generated HTML5 output. These parameter settings make the following
changes:</p>
<ul class="ul">
<li class="li">
<p class="p">Specify the <span class="ph filepath">css</span> subfolder of the plug-in as the source directory for custom CSS with
<span class="keyword parmname">args.cssroot</span>.</p></li>
<li class="li">
<p class="p">Specify the name of the custom CSS file with <span class="keyword parmname">args.css</span>.</p>
<p class="p">The value of this parameter tells DITA-OT to use the <span class="ph filepath">custom.css</span> file provided by the
plug-in.</p></li>
<li class="li">
<p class="p">Ensure that the CSS file is copied to the output directory by setting <span class="keyword parmname">args.copycss</span> to
<span class="keyword option">yes</span>.</p></li>
<li class="li">
<p class="p">Set the destination path for CSS files in the output folder with <span class="keyword parmname">args.csspath</span>.</p>
<p class="p">CSS files are copied to the root level of the output folder by default. Setting this parameter places CSS
files in a dedicated <span class="ph filepath">css</span> subfolder.</p></li>
</ul>
<p class="p">All four parameters are set in the Ant script (<span class="ph filepath">build_html5-custom-css.xml</span>).</p>
</section>
<section><div class="tasklabel"><h2 class="sectiontitle tasklabel">Procedure</h2></div><ol class="ol steps"><li class="li step stepexpand">
<span class="ph cmd">In the <span class="ph filepath">plugins</span> directory, create a directory named
<span class="ph filepath">com.example.html5-custom-css</span>.</span>
</li><li class="li step stepexpand">
<span class="ph cmd">In the new <span class="ph filepath">com.example.html5-custom-css</span> directory, create a plug-in configuration file
(<span class="ph filepath">plugin.xml</span>) that declares the new <span class="keyword option">html5-custom-css</span> transformation and
its dependencies.</span>
<div class="itemgroup stepxmp">
<figure class="fig fignone"><figcaption><span class="fig--title-label">Figure 1. </span>Sample <span class="ph filepath">plugin.xml</span> file</figcaption>
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;?xml-model href="https://www.dita-ot.org/rng/plugin.rnc" type="application/relax-ng-compact-syntax"?&gt;
&lt;plugin id="com.example.html5-custom-css"&gt;
&lt;require plugin="org.dita.html5"/&gt;
&lt;transtype name="html5-custom-css" extends="html5" desc="HTML5 with custom CSS"/&gt;
&lt;feature extension="ant.import" file="build_html5-custom-css.xml"/&gt;
&lt;/plugin&gt;</code></pre>
</figure>
<div class="note note note_note"><span class="note__title">Note:</span> This plug-in will extend the default HTML5 transformation, so the <code class="keyword markupname xmlelement">&lt;require&gt;</code>
element explicitly defines <span class="ph filepath">org.dita.html5</span> as a dependency.</div>
</div>
</li><li class="li step stepexpand">
<span class="ph cmd">In the <span class="ph filepath">com.example.html5-custom-css</span> directory, create a subdirectory named
<span class="ph filepath">css</span>.</span>
</li><li class="li step stepexpand">
<span class="ph cmd">In the new <span class="ph filepath">css</span> subdirectory, create a file named <span class="ph filepath">custom.css</span> with
your custom CSS rules.</span>
<div class="itemgroup stepxmp">
<figure class="fig fignone"><figcaption><span class="fig--title-label">Figure 2. </span>Sample <span class="ph filepath">custom.css</span> file</figcaption>
<pre class="pre codeblock language-css normalize-space show-line-numbers show-whitespace"><code>/* These custom styles extend or override DITA Open Toolkit default styles. */
body {
color: red;
}</code></pre>
</figure>
<div class="note tip note_tip"><span class="note__title">Tip:</span> When you first create the plug-in, you may want to include a rule in your custom stylesheet
that makes it readily apparent when the custom styles are applied (the example above will change body text
to “red”). Once you have verified that the plug-in works as intended, replace the placeholder rule with your
own custom styles.</div>
</div>
</li><li class="li step stepexpand">
<span class="ph cmd">In the <span class="ph filepath">com.example.html5-custom-css</span> root directory, add an Ant script
(<span class="ph filepath">build_html5-custom-css.xml</span>) to define the transformation type.</span>
<div class="itemgroup stepxmp">
<figure class="fig fignone"><figcaption><span class="fig--title-label">Figure 3. </span>Sample build file: <span class="ph filepath">build_html5-custom-css.xml</span></figcaption>
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;?xml version='1.0' encoding='UTF-8'?&gt;
&lt;project&gt;
&lt;target name="dita2html5-custom-css"
depends="dita2html5-custom-css.init,
dita2html5"/&gt;
&lt;target name="dita2html5-custom-css.init"&gt;
&lt;property name="args.cssroot"
location="${dita.plugin.com.example.html5-custom-css.dir}/css"/&gt;
&lt;property name="args.css" value="custom.css"/&gt;
&lt;property name="args.copycss" value="yes"/&gt;
&lt;property name="args.csspath" value="css"/&gt;
&lt;/target&gt;
&lt;/project&gt;</code></pre>
</figure>
</div>
</li></ol></section>
<section class="section result"><div class="tasklabel"><h2 class="sectiontitle tasklabel">Results</h2></div>
<div class="note tip note_tip"><span class="note__title">Tip:</span> The files for this sample plug-in are included in the DITA-OT installation directory under
<span class="ph filepath">docsrc/samples/plugins/com.example.html5-custom-css/</span> and on
<a class="xref" href="https://github.com/dita-ot/docs/tree/develop/samples/plugins/com.example.html5-custom-css" target="_blank" rel="external noopener">GitHub</a>.</div>
<p class="p">The plug-in directory has the following layout and files:</p>
<pre class="pre codeblock"><code>com.example.html5-custom-css
├── build_html5-custom-css.xml
├── css
│&nbsp;&nbsp; └── custom.css
└── plugin.xml</code></pre>
</section>
<section class="section postreq"><div class="tasklabel"><h2 class="sectiontitle tasklabel">What to do next</h2></div>
<ol class="ol">
<li class="li">Run <span class="ph filepath"><span class="keyword cmdname">dita</span></span>
<span class="keyword parmname">--install</span> to install the plug-in and make the <span class="keyword option">html5-custom-css</span>
transformation available.</li>
<li class="li">Build output with the new transformation type to verify that the plug-in works as intended.
<pre class="pre codeblock"><code><span class="ph filepath"><span class="keyword cmdname">dita</span></span> <span class="keyword parmname">--input</span>=<var class="keyword varname">my.ditamap</var> <span class="keyword parmname">--format</span>=<span class="keyword option">html5-custom-css</span></code></pre>
</li>
<li class="li">Refine the styles in your <span class="ph filepath">custom.css</span> file as necessary.</li>
</ol>
</section>
</div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/html-customization-plugins.html" title="In addition to the basic modifications that can be made with parameter settings and property files, you can create custom HTML plug-ins that bundle custom fonts, JavaScript, and stylesheets; modify the HTML markup, or override other aspects of HTML processing.">Custom HTML plug-ins</a></div></div><div class="linklist reltasks"><strong>Related tasks</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/html-customization-css.html" title="To modify the appearance of the default HTML output that DITA Open Toolkit generates, you can reference a custom Cascading Style Sheet (CSS) file with the typography, colors, and other presentation aspects that define your corporate identity.">Adding custom CSS</a></li></ul></div><div class="linklist relref"><strong>Related reference</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../parameters/parameters-base-html.html" title="Certain parameters apply to all HTML-based transformation types: HTML5, XHTML, HTML&nbsp;Help, and Eclipse help.">HTML-based output parameters</a></li></ul></div></nav></article></main></body></html>

126
dita-ot-3.6/doc/topics/html-customization-plugin-javascript.html Normal file
View file

@ -0,0 +1,126 @@
<!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="JavaScript code can be bundled in a custom plug-in and automatically inserted into the generated HTML pages to enable web analytics or dynamic content delivery."><meta name="keywords" content=", footer, require, head, HTML5, JavaScript, adding"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Inserting JavaScript in generated HTML</title></head><body id="custom-html-plugin-webfont"><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><ul><li><a href="../topics/html-customization-plugin-bundle-css.html">Bundling custom CSS</a></li><li><a href="../topics/html-customization-plugin-webfont.html">Embedding web fonts</a></li><li class="active"><a href="../topics/html-customization-plugin-javascript.html">Inserting JavaScript</a></li></ul></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></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">Inserting JavaScript in generated HTML</h1>
<div class="body taskbody"><p class="shortdesc">JavaScript code can be bundled in a custom plug-in and automatically inserted into the generated HTML pages
to enable web analytics or dynamic content delivery.</p>
<section class="section context"><div class="tasklabel"><h2 class="sectiontitle tasklabel">About this task</h2></div>
<p class="p">This scenario walks through the process of creating a very simple plug-in
(<code class="ph codeph">com.example.html5-javascript</code>) that creates a new transformation type:
<span class="keyword option">html5-javascript</span>. </p>
<p class="p">The <span class="keyword option">html5-javascript</span> transformation includes a custom page footer file with a JavaScript
tracking snippet and sets the <span class="keyword parmname">args.ftr</span> parameter to integrate the script content in the
HTML5 <code class="keyword markupname xmlelement">&lt;footer&gt;</code> element of the generated pages.</p>
<div class="note note note_note"><span class="note__title">Note:</span> This example inserts a tracking snippet for Google Analytics, but the basic approach is the same for other
analytics platforms or similar use cases that require custom JavaScript.</div>
</section>
<section><div class="tasklabel"><h2 class="sectiontitle tasklabel">Procedure</h2></div><ol class="ol steps"><li class="li step stepexpand">
<span class="ph cmd">In the <span class="ph filepath">plugins</span> directory, create a directory named
<span class="ph filepath">com.example.html5-javascript</span>.</span>
</li><li class="li step stepexpand">
<span class="ph cmd">In the new <span class="ph filepath">com.example.html5-javascript</span> directory, create a plug-in configuration file
(<span class="ph filepath">plugin.xml</span>) that declares the new <span class="keyword option">html5-javascript</span> transformation and
its dependencies.</span>
<div class="itemgroup stepxmp">
<figure class="fig fignone"><figcaption><span class="fig--title-label">Figure 1. </span>Sample <span class="ph filepath">plugin.xml</span> file</figcaption>
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;?xml-model href="https://www.dita-ot.org/rng/plugin.rnc" type="application/relax-ng-compact-syntax"?&gt;
&lt;plugin id="com.example.html5-javascript"&gt;
&lt;require plugin="org.dita.html5"/&gt;
&lt;transtype name="html5-javascript" extends="html5" desc="HTML5 with embedded JavaScript"/&gt;
&lt;feature extension="ant.import" file="build_html5-javascript.xml"/&gt;
&lt;/plugin&gt;</code></pre>
</figure>
<div class="note note note_note"><span class="note__title">Note:</span> This plug-in will extend the default HTML5 transformation, so the <code class="keyword markupname xmlelement">&lt;require&gt;</code>
element explicitly defines <span class="ph filepath">org.dita.html5</span> as a dependency.</div>
</div>
</li><li class="li step stepexpand">
<span class="ph cmd">In the <span class="ph filepath">com.example.html5-javascript</span> directory, create a subdirectory named
<span class="ph filepath">include</span>.</span>
</li><li class="li step stepexpand">
<span class="ph cmd">In the new <span class="ph filepath">include</span> subdirectory, create a file named
<span class="ph filepath">javascript.ftr.xml</span> with your custom JavaScript code.</span>
<div class="itemgroup stepxmp">
<figure class="fig fignone"><figcaption><span class="fig--title-label">Figure 2. </span>Sample <span class="ph filepath">javascript.ftr.xml</span> file</figcaption>
<pre class="pre codeblock language-javascript normalize-space show-line-numbers show-whitespace"><code>&lt;div&gt;
&lt;!-- Google Analytics --&gt;
&lt;script&gt;
console.log('Adding Google Analytics tracker');
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-XXXXX-Y', 'auto');
ga('send', 'pageview');
&lt;/script&gt;
&lt;!-- End Google Analytics --&gt;
&lt;/div&gt;</code></pre>
</figure>
<p class="p">The division wrapper will be discarded when generating HTML files, and the contents will be inserted into
the <code class="keyword markupname xmlelement">&lt;footer&gt;</code> element of each page.</p>
</div>
</li><li class="li step stepexpand">
<span class="ph cmd">In the <span class="ph filepath">com.example.html5-javascript</span> root directory, add an Ant script
(<span class="ph filepath">build_html5-javascript.xml</span>) to define the transformation type and set the path to the
JavaScript footer file created in the previous step.</span>
<div class="itemgroup stepxmp">
<figure class="fig fignone"><figcaption><span class="fig--title-label">Figure 3. </span>Sample build file: <span class="ph filepath">build_html5-javascript.xml</span></figcaption>
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;?xml version='1.0' encoding='UTF-8'?&gt;
&lt;project&gt;
&lt;target name="dita2html5-javascript"
depends="dita2html5-javascript.init,
dita2html5"/&gt;
&lt;target name="dita2html5-javascript.init"&gt;
&lt;property name="args.ftr"
location="${dita.plugin.com.example.html5-javascript.dir}/include/javascript.ftr.xml"/&gt;
&lt;/target&gt;
&lt;/project&gt;</code></pre>
</figure>
</div>
</li></ol></section>
<section class="section result"><div class="tasklabel"><h2 class="sectiontitle tasklabel">Results</h2></div>
<div class="note tip note_tip"><span class="note__title">Tip:</span> The files for this sample plug-in are included in the DITA-OT installation directory under
<span class="ph filepath">docsrc/samples/plugins/com.example.html5-javascript/</span> and on
<a class="xref" href="https://github.com/dita-ot/docs/tree/develop/samples/plugins/com.example.html5-javascript" target="_blank" rel="external noopener">GitHub</a>.</div>
<p class="p">The plug-in directory has the following layout and files:</p>
<pre class="pre codeblock"><code>com.example.html5-javascript
├── build_html5-javascript.xml
├── include
│&nbsp;&nbsp; └── javascript.ftr.xml
└── plugin.xml</code></pre>
</section>
<section class="section postreq"><div class="tasklabel"><h2 class="sectiontitle tasklabel">What to do next</h2></div>
<ol class="ol">
<li class="li">Run <span class="ph filepath"><span class="keyword cmdname">dita</span></span>
<span class="keyword parmname">--install</span> to install the plug-in and make the <span class="keyword option">html5-javascript</span>
transformation available.</li>
<li class="li">Build output with the new transformation type to verify that the plug-in works as intended.
<pre class="pre codeblock"><code><span class="ph filepath"><span class="keyword cmdname">dita</span></span> <span class="keyword parmname">--input</span>=<var class="keyword varname">my.ditamap</var> <span class="keyword parmname">--format</span>=<span class="keyword option">html5-javascript</span></code></pre></li>
<li class="li">Open one of the generated HTML topic files in a modern web browser and check the JavaScript
<span class="ph uicontrol">Console</span>. When the page is loaded, <samp class="ph msgph">Adding Google Analytics tracker</samp> will
appear on the console to verify that the sample script is loaded.</li>
<li class="li">Remove the <code class="ph codeph">console.log</code> debugging message from the sample JavaScript code, and replace the
<code class="ph codeph">'UA-XXXXX-Y'</code> placeholder string with the tracking ID of the Google Analytics property you
wish to track.</li>
</ol>
<div class="note tip note_tip"><span class="note__title">Tip:</span> This example places the JavaScript code in the page footer to ensure that page display is not
delayed while the script is loaded. If your JavaScript code supports pre-loading and your application targets
modern browsers that recognize the <code class="ph codeph">async</code> script attribute, you may prefer to insert the
JavaScript snippet in the <code class="keyword markupname xmlelement">&lt;head&gt;</code> element of the generated HTML files using the
<span class="keyword parmname">args.hdf</span> parameter instead.</div>
</section>
</div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/html-customization-plugins.html" title="In addition to the basic modifications that can be made with parameter settings and property files, you can create custom HTML plug-ins that bundle custom fonts, JavaScript, and stylesheets; modify the HTML markup, or override other aspects of HTML processing.">Custom HTML plug-ins</a></div></div><div class="linklist relref"><strong>Related reference</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../parameters/parameters-base-html.html" title="Certain parameters apply to all HTML-based transformation types: HTML5, XHTML, HTML&nbsp;Help, and Eclipse help.">HTML-based output parameters</a></li></ul></div></nav></article></main></body></html>

148
dita-ot-3.6/doc/topics/html-customization-plugin-webfont.html Normal file
View file

@ -0,0 +1,148 @@
<!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="A custom plug-in can be created to generate HTML output that uses custom fonts for enhanced typographic features, extended character sets or a unique corporate identity."><meta name="keywords" content=", require, link, head, HTML, custom plug-in, fonts, CSS, web fonts, fonts, HTML, web fonts, custom.css, build_html5-webfont.xml, plugin.xml, org.dita.html5"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Embedding web fonts in HTML output</title></head><body id="custom-html-plugin-webfont"><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><ul><li><a href="../topics/html-customization-plugin-bundle-css.html">Bundling custom CSS</a></li><li class="active"><a href="../topics/html-customization-plugin-webfont.html">Embedding web fonts</a></li><li><a href="../topics/html-customization-plugin-javascript.html">Inserting JavaScript</a></li></ul></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></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">Embedding web fonts in HTML output</h1>
<div class="body taskbody"><p class="shortdesc">A custom plug-in can be created to generate HTML output that uses custom fonts for enhanced typographic
features, extended character sets or a unique corporate identity.</p>
<section class="section context"><div class="tasklabel"><h2 class="sectiontitle tasklabel">About this task</h2></div>
<p class="p">This scenario walks through the process of creating a very simple plug-in
(<code class="ph codeph">com.example.html5-webfont</code>) that creates a new transformation type:
<span class="keyword option">html5-webfont</span>. </p>
<p class="p">The <span class="keyword option">html5-webfont</span> transformation includes a custom CSS file and sets five parameters to
integrate font links and a custom stylesheet in the generated HTML5 output. These parameter settings make the
following changes:</p>
<ul class="ul">
<li class="li">
<p class="p">Specify a file that links to the font from the document head with <span class="keyword parmname">args.hdf</span>.</p></li>
<li class="li">
<p class="p">Specify the <span class="ph filepath">css</span> subfolder of the plug-in as the source directory for custom CSS with
<span class="keyword parmname">args.cssroot</span>.</p></li>
<li class="li">
<p class="p">Specify the name of the custom CSS file with <span class="keyword parmname">args.css</span>.</p>
<p class="p">The value of this parameter tells DITA-OT to use the <span class="ph filepath">custom.css</span> file provided by the
plug-in.</p></li>
<li class="li">
<p class="p">Ensure that the CSS file is copied to the output directory by setting <span class="keyword parmname">args.copycss</span> to
<span class="keyword option">yes</span>.</p></li>
<li class="li">
<p class="p">Set the destination path for CSS files in the output folder with <span class="keyword parmname">args.csspath</span>.</p>
<p class="p">CSS files are copied to the root level of the output folder by default. Setting this parameter places CSS
files in a dedicated <span class="ph filepath">css</span> subfolder.</p></li>
</ul>
<p class="p">All five parameters are set in the Ant script (<span class="ph filepath">build_html5-webfont.xml</span>).</p>
</section>
<section><div class="tasklabel"><h2 class="sectiontitle tasklabel">Procedure</h2></div><ol class="ol steps"><li class="li step stepexpand">
<span class="ph cmd">In the <span class="ph filepath">plugins</span> directory, create a directory named
<span class="ph filepath">com.example.html5-webfont</span>.</span>
</li><li class="li step stepexpand">
<span class="ph cmd">In the new <span class="ph filepath">com.example.html5-webfont</span> directory, create a plug-in configuration file
(<span class="ph filepath">plugin.xml</span>) that declares the new <span class="keyword option">html5-webfont</span> transformation and
its dependencies.</span>
<div class="itemgroup stepxmp">
<figure class="fig fignone"><figcaption><span class="fig--title-label">Figure 1. </span>Sample <span class="ph filepath">plugin.xml</span> file</figcaption>
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;?xml-model href="https://www.dita-ot.org/rng/plugin.rnc" type="application/relax-ng-compact-syntax"?&gt;
&lt;plugin id="com.example.html5-webfont"&gt;
&lt;require plugin="org.dita.html5"/&gt;
&lt;transtype name="html5-webfont" extends="html5" desc="HTML5 with Noto Sans webfont"/&gt;
&lt;feature extension="ant.import" file="build_html5-webfont.xml"/&gt;
&lt;/plugin&gt;</code></pre>
</figure>
<div class="note note note_note"><span class="note__title">Note:</span> This plug-in will extend the default HTML5 transformation, so the <code class="keyword markupname xmlelement">&lt;require&gt;</code>
element explicitly defines <span class="ph filepath">org.dita.html5</span> as a dependency.</div>
</div>
</li><li class="li step stepexpand">
<span class="ph cmd">In the <span class="ph filepath">com.example.html5-webfont</span> directory, create a subdirectory named
<span class="ph filepath">include</span>.</span>
</li><li class="li step stepexpand">
<span class="ph cmd">In the new <span class="ph filepath">include</span> subdirectory, create a file named
<span class="ph filepath">webfont.hdf.xml</span> with your custom font links.</span>
<div class="itemgroup stepxmp">
<figure class="fig fignone"><figcaption><span class="fig--title-label">Figure 2. </span>Sample <span class="ph filepath">webfont.hdf.xml</span> file</figcaption>
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;div&gt;
&lt;link href="https://fonts.googleapis.com/css?family=Noto+Sans" rel="stylesheet"/&gt;
&lt;/div&gt;</code></pre>
</figure>
<p class="p">This example uses the
<a class="xref" href="https://fonts.google.com/specimen/Noto+Sans" target="_blank" rel="external noopener">Noto Sans</a> font. You can use multiple fonts by creating additional
<code class="keyword markupname xmlelement">&lt;link&gt;</code> references in this file. The division wrapper will be discarded when
generating HTML files, and the contents will be inserted into the <code class="keyword markupname xmlelement">&lt;head&gt;</code> element of
each page.</p>
</div>
</li><li class="li step stepexpand">
<span class="ph cmd">In the <span class="ph filepath">com.example.html5-webfont</span> directory, create a subdirectory named
<span class="ph filepath">css</span>.</span>
</li><li class="li step stepexpand">
<span class="ph cmd">In the new <span class="ph filepath">css</span> subdirectory, create a file named <span class="ph filepath">custom.css</span> with
the stylesheet rules that apply the custom <code class="ph codeph">font-family</code> to the desired elements.</span>
<div class="itemgroup stepxmp">
<figure class="fig fignone"><figcaption><span class="fig--title-label">Figure 3. </span>Sample <span class="ph filepath">custom.css</span> file</figcaption>
<pre class="pre codeblock language-css normalize-space show-line-numbers show-whitespace"><code>body {
font-family: 'Noto Sans', sans-serif;
}</code></pre>
</figure>
<p class="p">This example uses
<a class="xref" href="https://fonts.google.com/specimen/Noto+Sans" target="_blank" rel="external noopener">Noto Sans</a> for all body content. In practice, you would normally use different fonts
for headings, body content, tables, etc. by creating additional rules in your CSS file.</p>
</div>
</li><li class="li step stepexpand">
<span class="ph cmd">In the <span class="ph filepath">com.example.html5-webfont</span> root directory, add an Ant script
(<span class="ph filepath">build_html5-webfont.xml</span>) to define the transformation type.</span>
<div class="itemgroup stepxmp">
<figure class="fig fignone"><figcaption><span class="fig--title-label">Figure 4. </span>Sample build file: <span class="ph filepath">build_html5-webfont.xml</span></figcaption>
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;?xml version='1.0' encoding='UTF-8'?&gt;
&lt;project&gt;
&lt;target name="dita2html5-webfont"
depends="dita2html5-webfont.init,
dita2html5"/&gt;
&lt;target name="dita2html5-webfont.init"&gt;
&lt;property name="args.hdf"
location="${dita.plugin.com.example.html5-webfont.dir}/include/webfont.hdf.xml"/&gt;
&lt;property name="args.cssroot"
location="${dita.plugin.com.example.html5-webfont.dir}/css"/&gt;
&lt;property name="args.css" value="custom.css"/&gt;
&lt;property name="args.copycss" value="yes"/&gt;
&lt;property name="args.csspath" value="css"/&gt;
&lt;/target&gt;
&lt;/project&gt;</code></pre>
</figure>
</div>
</li></ol></section>
<section class="section result"><div class="tasklabel"><h2 class="sectiontitle tasklabel">Results</h2></div>
<div class="note tip note_tip"><span class="note__title">Tip:</span> The files for this sample plug-in are included in the DITA-OT installation directory under
<span class="ph filepath">docsrc/samples/plugins/com.example.html5-webfont/</span> and on
<a class="xref" href="https://github.com/dita-ot/docs/tree/develop/samples/plugins/com.example.html5-webfont" target="_blank" rel="external noopener">GitHub</a>.</div>
<p class="p">The plug-in directory has the following layout and files:</p>
<pre class="pre codeblock"><code>com.example.html5-webfont
├── build_html5-webfont.xml
├── css
│&nbsp;&nbsp; └── custom.css
├── include
│&nbsp;&nbsp; └── webfont.hdf.xml
└── plugin.xml</code></pre>
</section>
<section class="section postreq"><div class="tasklabel"><h2 class="sectiontitle tasklabel">What to do next</h2></div>
<ol class="ol">
<li class="li">Run <span class="ph filepath"><span class="keyword cmdname">dita</span></span>
<span class="keyword parmname">--install</span> to install the plug-in and make the <span class="keyword option">html5-webfont</span>
transformation available.</li>
<li class="li">Build output with the new transformation type to verify that the plug-in works as intended.
<pre class="pre codeblock"><code><span class="ph filepath"><span class="keyword cmdname">dita</span></span> <span class="keyword parmname">--input</span>=<var class="keyword varname">my.ditamap</var> <span class="keyword parmname">--format</span>=<span class="keyword option">html5-webfont</span></code></pre>
</li>
<li class="li">Refine the styles in your <span class="ph filepath">custom.css</span> file to adjust the font usage as necessary.</li>
</ol>
</section>
</div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/html-customization-plugins.html" title="In addition to the basic modifications that can be made with parameter settings and property files, you can create custom HTML plug-ins that bundle custom fonts, JavaScript, and stylesheets; modify the HTML markup, or override other aspects of HTML processing.">Custom HTML plug-ins</a></div></div><div class="linklist relref"><strong>Related reference</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../parameters/parameters-base-html.html" title="Certain parameters apply to all HTML-based transformation types: HTML5, XHTML, HTML&nbsp;Help, and Eclipse help.">HTML-based output parameters</a></li></ul></div></nav></article></main></body></html>

16
dita-ot-3.6/doc/topics/html-customization-plugins.html Normal file
View file

@ -0,0 +1,16 @@
<!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="In addition to the basic modifications that can be made with parameter settings and property files, you can create custom HTML plug-ins that bundle custom fonts, JavaScript, and stylesheets; modify the HTML markup, or override other aspects of HTML processing."><meta name="keywords" content="HTML, custom plug-in, fonts, JavaScript, CSS, markup, adding, CSS, HTML, fonts"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Custom HTML plug-ins</title></head><body id="custom-html-plugins"><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 class="active"><a href="../topics/html-customization-plugins.html">Custom HTML plug-ins</a><ul><li><a href="../topics/html-customization-plugin-bundle-css.html">Bundling custom CSS</a></li><li><a href="../topics/html-customization-plugin-webfont.html">Embedding web fonts</a></li><li><a href="../topics/html-customization-plugin-javascript.html">Inserting JavaScript</a></li></ul></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></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">Custom HTML plug-ins</h1>
<div class="body conbody"><p class="shortdesc">In addition to the basic modifications that can be made with parameter settings and property files, you can
create custom HTML plug-ins that bundle custom fonts, JavaScript, and stylesheets; modify the HTML markup, or
override other aspects of HTML processing.</p>
<div class="note note note_note"><span class="note__title">Note:</span> These examples are not intended to be used as-is, but illustrate basic techniques you can use in your own
plug-ins. In practise, custom plug-ins often combine several of these approaches.</div>
</div>
<nav role="navigation" class="related-links"><ul class="ullinks"><li class="link ulchildlink"><strong><a href="../topics/html-customization-plugin-bundle-css.html">Bundling CSS in a custom HTML plug-in</a></strong><br>You can create a DITA-OT plug-in that provides a custom stylesheet with the typography and colors that define your corporate identity. Coworkers can install this plug-in to ensure consistent HTML output across projects without having to copy the stylesheet to each project.</li><li class="link ulchildlink"><strong><a href="../topics/html-customization-plugin-webfont.html">Embedding web fonts in HTML output</a></strong><br>A custom plug-in can be created to generate HTML output that uses custom fonts for enhanced typographic features, extended character sets or a unique corporate identity.</li><li class="link ulchildlink"><strong><a href="../topics/html-customization-plugin-javascript.html">Inserting JavaScript in generated HTML</a></strong><br>JavaScript code can be bundled in a custom plug-in and automatically inserted into the generated HTML pages to enable web analytics or dynamic content delivery.</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 relconcepts"><strong>Related concepts</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/plugin-coding-conventions.html" title="To ensure custom plug-ins work well with the core toolkit code and remain compatible with future releases, the DITA Open Toolkit project recommends that plug-ins use modern development practices and common coding patterns.">Plug-in coding conventions</a></li></ul></div><div class="linklist reltasks"><strong>Related tasks</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/html-customization.html" title="You can modify the look and feel of your HTML output by changing parameter settings to include custom CSS, headers and footers, or table-of-contents navigation in topics.">Customizing HTML output</a></li></ul></div></nav></article></main></body></html>

57
dita-ot-3.6/doc/topics/html-customization-properties-file.html Normal file
View file

@ -0,0 +1,57 @@
<!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="You can also use a .properties file to reference a set of build parameters when building output with the dita command. The DITA-OT documentation uses a .properties file to include custom CSS, header branding, and table-of-contents navigation in the HTML5 output."><meta name="keywords" content="command, dita, .properties file, HTML, build properties, CSS"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Customizing HTML with a .properties file</title></head><body id="custom-html-properties-file"><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><ul><li><a href="../topics/html-customization-parameters.html">Setting HTML parameters</a></li><li class="active"><a href="../topics/html-customization-properties-file.html">Using a properties file</a></li></ul></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></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">Customizing HTML with a <span class="ph filepath">.properties</span> file</h1>
<div class="body taskbody"><p class="shortdesc">You can also use a <span class="ph filepath">.properties</span> file to reference a set of build parameters when
building output with the <span class="keyword cmdname">dita</span> command. The DITA-OT documentation uses a
<span class="ph filepath">.properties</span> file to include custom CSS, header branding, and table-of-contents navigation in
the HTML5 output.</p>
<section><div class="tasklabel"><h2 class="sectiontitle tasklabel">Procedure</h2></div><ol class="ol steps"><li class="li step stepexpand">
<span class="ph cmd">Create a <span class="ph filepath">.properties</span> file to store the parameter settings for your
customization.</span>
<div class="itemgroup info">
<div class="note tip note_tip"><span class="note__title">Tip:</span> You can use one of the sample <span class="ph filepath">.properties</span> files from the DITA-OT
documentation as a starting point for your own customizations. These files are available in the installation
folder under <span class="ph filepath">docsrc/samples/properties/</span>.</div>
</div>
<div class="itemgroup stepxmp">
<p class="p">For example:</p>
<figure class="fig fignone"><figcaption><span class="fig--title-label">Figure 1. </span>The <span class="ph filepath">docsrc/samples/properties/sequence-html5.properties</span> file</figcaption>
<pre class="pre codeblock language-properties normalize-space show-line-numbers show-whitespace"><code># Directory that contains the custom .css file:
args.cssroot = ${args.input.dir}/css/
# Custom .css file used to style output:
args.css = style.css
# Copy the custom .css file to the output directory:
args.copycss = yes
# Location of the copied .css file relative to the output:
args.csspath = branding
# Generate a full navigation TOC in topic pages:
nav-toc = full</code></pre>
</figure>
</div>
</li><li class="li step stepexpand">
<span class="ph cmd">Reference your <span class="ph filepath">.properties</span> file with the <span class="keyword cmdname">dita</span> command when building
your output.</span>
<div class="itemgroup stepxmp">
<pre class="pre codeblock syntax-bash"><code><span class="keyword cmdname">dita</span> <span class="keyword parmname">--input</span>=<var class="keyword varname">my.ditamap</var> <span class="keyword parmname">--format</span>=<span class="keyword option">html5</span> <span class="keyword parmname">--propertyfile</span>=<var class="keyword varname">my.properties</var></code></pre>
</div>
<div class="itemgroup info"></div>
</li></ol></section>
<section class="section result"><div class="tasklabel"><h2 class="sectiontitle tasklabel">Results</h2></div>
<div class="note note note_note"><span class="note__title">Note:</span> For an example of HTML output generated using this method, see the HTML5 version of the DITA-OT
documentation included in the installation folder under <span class="ph filepath">doc/index.html</span>.</div>
</section>
</div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/html-customization.html" title="You can modify the look and feel of your HTML output by changing parameter settings to include custom CSS, headers and footers, or table-of-contents navigation in topics.">Customizing HTML output</a></div></div><div class="linklist reltasks"><strong>Related tasks</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/html-customization-parameters.html" title="For simple branded HTML pages, you can adjust the look and feel of the default output to match your company style by setting parameters to include custom CSS, header branding, or table-of-contents navigation in topics. (These changes do not require a custom plug-in.)">Setting parameters for custom HTML</a></li></ul></div></nav></article></main></body></html>

12
dita-ot-3.6/doc/topics/html-customization.html Normal file
View file

@ -0,0 +1,12 @@
<!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="You can modify the look and feel of your HTML output by changing parameter settings to include custom CSS, headers and footers, or table-of-contents navigation in topics."><meta name="keywords" content="HTML, customizing, transformations, HTML, plug-ins, HTML5"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Customizing HTML output</title></head><body id="customizing-html-output"><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 class="active"><a href="../topics/html-customization.html">Customizing HTML</a><ul><li><a href="../topics/html-customization-parameters.html">Setting HTML parameters</a></li><li><a href="../topics/html-customization-properties-file.html">Using a properties file</a></li></ul></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></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">Customizing HTML output</h1>
<p class="shortdesc">You can <span class="ph" id="customizing-html-output__shortdesc-ph">modify the look and feel of your HTML output by changing parameter settings
to include custom CSS, headers and footers, or table-of-contents navigation in topics</span>.</p>
<nav role="navigation" class="related-links"><ul class="ullinks"><li class="link ulchildlink"><strong><a href="../topics/html-customization-parameters.html">Setting parameters for custom HTML</a></strong><br>For simple branded HTML pages, you can adjust the look and feel of the default output to match your company style by setting parameters to include custom CSS, header branding, or table-of-contents navigation in topics. (These changes do not require a custom plug-in.)</li><li class="link ulchildlink"><strong><a href="../topics/html-customization-properties-file.html">Customizing HTML with a .properties file</a></strong><br>You can also use a <span class="ph filepath">.properties</span> file to reference a set of build parameters when building output with the <span class="keyword cmdname">dita</span> command. The DITA-OT documentation uses a <span class="ph filepath">.properties</span> file to include custom CSS, header branding, and table-of-contents navigation in the HTML5 output.</li></ul><div class="linklist relconcepts"><strong>Related concepts</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/html-customization-plugins.html" title="In addition to the basic modifications that can be made with parameter settings and property files, you can create custom HTML plug-ins that bundle custom fonts, JavaScript, and stylesheets; modify the HTML markup, or override other aspects of HTML processing.">Custom HTML plug-ins</a></li></ul></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/2017/dita-ot_day.html#Bootstrapping_DITA" target="_blank" rel="external noopener" title="Web developers often use CSS frameworks, HTML5 boilerplate or component libraries like Bootstrap or Foundation to quickly build robust, responsive sites. With custom HTML plug-ins, DITA-OT can be extended to produce HTML5 output that makes use of these common templates so that generated documents can build on existing front-end solutions. This talk will outline the process, using the DITA-OT project website at dita-ot.org as an example.">Bootstrapping DITA - Customizing HTML output for modern web frameworks</a></li></ul></div></nav></article></main></body></html>

84
dita-ot-3.6/doc/topics/implement-saxon-collation-uri-resolvers.html Normal file
View file

@ -0,0 +1,84 @@
<!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="Plug-ins can provide custom URI resolvers that provide collators for specific collation URIs."><meta name="keywords" content="Saxon, service, Ant, jar, xsl:sort, Chinese, I18N, plug-in, XSLT, URI resolver"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Implementing custom Saxon collation URI resolvers</title></head><body id="implement-saxon-collation-uri-resolvers"><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><ul><li><a href="../topics/plugin-set-parameters.html">Setting parameters</a></li><li><a href="../topics/plugin-anttarget.html">Adding a new Ant target</a></li><li><a href="../topics/plugin-antpreprocess.html">Adding a pre-processing step</a></li><li><a href="../topics/plugin-newtranstype.html">Adding a new output format</a></li><li><a href="../topics/plugin-xsltparams.html">Adding new parameters</a></li><li><a href="../topics/plugin-overridestyle.html">Overriding XSLT steps</a></li><li><a href="../topics/plugin-javalib.html">Adding a Java library</a></li><li><a href="../topics/plugin-messages.html">Adding new messages</a></li><li><a href="../topics/plugin-newextensions.html">New extension points</a></li><li><a href="../topics/plugin-xmlcatalog.html">Extending an XML catalog file</a></li><li><a href="../topics/plugin-rewrite-rules.html">Rewriting file names</a></li><li><a href="../topics/implement-saxon-customizations.html">Saxon customizations</a><ul><li><a href="../topics/implement-saxon-extension-functions.html">Saxon extensions</a></li><li class="active"><a href="../topics/implement-saxon-collation-uri-resolvers.html">Custom collation URI resolvers</a></li></ul></li></ul></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></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">Implementing custom Saxon collation URI resolvers</h1>
<div class="body"><p class="shortdesc">Plug-ins can provide custom URI resolvers that provide collators for specific collation URIs.</p>
<p class="p">To do custom sorting and grouping in XSLT, you identify collators using URIs that Saxon resolves to collator
implementations. You implement the mapping from collation URIs to collators through custom collation URI
resolvers.</p>
<p class="p">For example, the DITA Community I18N plugin provides a custom collator for doing dictionary-based sorting and
grouping of Simplified Chinese. </p>
<p class="p">To allow multiple plug-ins to contribute collation URI resolvers, DITA-OT defines a superinterface of Saxon’s
<code class="ph codeph">CollationUriResolver</code> interface,
<code class="ph codeph">org.dita.dost.module.saxon.DelegatingCollationUriResolver</code>, that takes a base resolver.</p>
<p class="p">Implementations of <code class="ph codeph">DelegatingCollationUriResolver</code> should delegate to their base resolver if they
do not resolve the URI specified on the resolve request. When multiple plug-ins provide resolvers it results in a
chain of resolvers, ending with the built-in Saxon default resolver.</p>
<div class="note note note_note"><span class="note__title">Note:</span> The order in which plug-ins will be processed during collation URI resolver configuration is variable, so two
plug-ins should not try to resolve the same collation URI. In that case the first one configured will be used at
run time.</div>
<div class="p">A typical delegating collation URI resolver looks like
this:<pre class="pre codeblock language-java"><code>public class DCI18nCollationUriResolver implements DelegatingCollationUriResolver {
public static final String DITA_COMMUNITY_I18N_ZH_CNAWARE_COLLATOR =
"http://org.dita-community.i18n.zhCNawareCollator";
public static final String LANG_URI_PARAM = "lang";
private CollationURIResolver baseResolver;
public DCI18nCollationUriResolver() {
super();
this.baseResolver = StandardCollationURIResolver.getInstance();
}
public net.sf.saxon.lib.StringCollator resolve(String uri, Configuration configuration)
throws XPathException {
ZhCnAwareCollator collator = resolveToZhCnAwareCollator(uri, null, configuration);
if (null == collator) {
return baseResolver.resolve(uri, configuration);
}
return (StringCollator) collator;
}
@Override
public void setBaseResolver(CollationURIResolver baseResolver) {
this.baseResolver = baseResolver;
}
/* ... Code to evaluate the collation URI and provide the appropriate collator goes here */
}</code></pre></div>
<div class="p">To implement a custom collation URI resolver:
<ol class="ol">
<li class="li">Add your plugin’s JAR file in the DITA-OT class path as described in
<a class="xref" href="plugin-javalib.html" title="You can use the dita.conductor.lib.import extension point to add an additional Java library to the DITA-OT classpath parameter.">Adding a Java library to the classpath</a>.</li>
<li class="li">Implement an instance of <code class="ph codeph">org.dita.dost.module.saxon.DelegatingCollationUriResolver</code> as
described above.</li>
<li class="li">Include a file named <span class="ph filepath">org.dita.dost.module.saxon.DelegatingCollationUriResolver</span> in the
directory <span class="ph filepath">META-INF/services</span> in the compiled JAR that your plug-in provides. Each line of
the file must be the name of a class that implements
<code class="ph codeph">org.dita.dost.module.saxon.DelegatingCollationUriResolver</code>:<pre class="pre codeblock"><code>org.example.i18n.saxon.MyCollationUriResolver</code></pre>
<div class="p">You can create the services file using <code class="keyword markupname xmlelement">&lt;service&gt;</code> elements in an Ant
<code class="keyword markupname xmlelement">&lt;jar&gt;</code>
task:<pre class="pre codeblock language-xml"><code>&lt;jar destfile="${basedir}/target/lib/example-saxon.jar"&gt;
⋮
&lt;service type="org.dita.dost.module.saxon.DelegatingCollationUriResolver"&gt;
&lt;provider classname="org.example.i18n.saxon.MyCollationUriResolver"/&gt;
&lt;/service&gt;
⋮
&lt;/jar&gt;</code></pre></div></li>
<li class="li">To use the collator in XSLT style sheets, specify the collation URI on <code class="keyword markupname xmlatt">@xsl:sort</code> elements
(or anywhere a collator URI can be
specified):<pre class="pre codeblock language-xml"><code>&lt;xsl:apply-templates select="word"&gt;
&lt;xsl:sort collation="http://org.example.i18n.MyCollator"/&gt;
&lt;/xsl:apply-templates&gt;</code></pre></li>
</ol></div>
</div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/implement-saxon-customizations.html" title="Plug-ins can contribute XSLT extension functions and collation URI resolvers. These customizations are automatically configured to work with Saxon when transformations are run using the DITA-OT pipeline task with custom XSLT.">Adding Saxon customizations</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/2015/dita-ot_day.html#DITA_Community" target="_blank" rel="external noopener" title="The DITA Community GitHub organization serves as a general place for people to contribute DITA Open Toolkit plugins and other DITA-related tools and utilities that are not maintained by DITA-OT or other projects. This presentation provides an overview of the DITA Community organization, what's there today, and how you can contribute.">DITA Community</a></li></ul></div></nav></article></main></body></html>

44
dita-ot-3.6/doc/topics/implement-saxon-customizations.html Normal file
View file

@ -0,0 +1,44 @@
<!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="Plug-ins can contribute XSLT extension functions and collation URI resolvers. These customizations are automatically configured to work with Saxon when transformations are run using the DITA-OT pipeline task with custom XSLT."><meta name="keywords" content="Saxon, service, Ant, jar, pipeline, xslt, Ant, Saxon, I18N, plug-in, plug-ins, XSLT, preprocessing, extension points, Saxon, Java, ServiceLoader"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Adding Saxon customizations</title></head><body id="implement-saxon-customizations"><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><ul><li><a href="../topics/plugin-set-parameters.html">Setting parameters</a></li><li><a href="../topics/plugin-anttarget.html">Adding a new Ant target</a></li><li><a href="../topics/plugin-antpreprocess.html">Adding a pre-processing step</a></li><li><a href="../topics/plugin-newtranstype.html">Adding a new output format</a></li><li><a href="../topics/plugin-xsltparams.html">Adding new parameters</a></li><li><a href="../topics/plugin-overridestyle.html">Overriding XSLT steps</a></li><li><a href="../topics/plugin-javalib.html">Adding a Java library</a></li><li><a href="../topics/plugin-messages.html">Adding new messages</a></li><li><a href="../topics/plugin-newextensions.html">New extension points</a></li><li><a href="../topics/plugin-xmlcatalog.html">Extending an XML catalog file</a></li><li><a href="../topics/plugin-rewrite-rules.html">Rewriting file names</a></li><li class="active"><a href="../topics/implement-saxon-customizations.html">Saxon customizations</a><ul><li><a href="../topics/implement-saxon-extension-functions.html">Saxon extensions</a></li><li><a href="../topics/implement-saxon-collation-uri-resolvers.html">Custom collation URI resolvers</a></li></ul></li></ul></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></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">Adding Saxon customizations</h1>
<div class="body"><p class="shortdesc">Plug-ins can contribute XSLT extension functions and collation URI resolvers. These customizations are
automatically configured to work with Saxon when transformations are run using the DITA-OT
<code class="keyword markupname xmlelement">&lt;pipeline&gt;</code> task with custom XSLT.</p>
<div class="p">Plug-ins can provide the following Saxon extensions:
<ul class="ul">
<li class="li">Extension functions</li>
<li class="li">Collation URI resolvers</li>
</ul></div>
<p class="p">Extensions are declared in plug-in-provided JAR files using the Java ServiceLoader feature that looks for
service-declaring files in JAR files and loads classes. This requires adding one or more files in the
<span class="ph filepath">META-INF/services</span> directory in plug-in-provided JAR files.</p>
<p class="p">You can create the file manually or generate it dynamically using <code class="keyword markupname xmlelement">&lt;service&gt;</code> elements in
Ant <code class="keyword markupname xmlelement">&lt;jar&gt;</code> tasks. See the topics for the different extension types for details.</p>
<div class="p">These extensions use the DITA Open Toolkit Ant <code class="keyword markupname xmlelement">&lt;pipeline&gt;</code> element to wrap
<code class="keyword markupname xmlelement">&lt;xslt&gt;</code> elements. You can do this in plug-ins as shown in this excerpt from the DITA
Community I18N plugin’s <span class="ph filepath">build.xml</span>
file:<pre class="pre codeblock language-xml"><code>&lt;target name="org.dita-community.i18n-saxon-extension-test"&gt;
&lt;pipeline message="Test the DITA Community i18n Saxon extension functions"
taskname="i18n-extension-function-test"&gt;
&lt;xslt
in="${dita.plugin.org.dita-community.i18n.dir}/test/xsl/data/test-data.xml"
style="${dita.plugin.org.dita-community.i18n.dir}/test/xsl/test-extension-functions.xsl"
out="${basedir}/out/extension-function-test-results.xml"
&gt;
&lt;/xslt&gt;
&lt;/pipeline&gt;
&lt;/target&gt;</code></pre></div>
<p class="p">Normal XSLT extensions to built-in transformation types will automatically have the extensions available to
them.</p>
<p class="p">The dynamic Saxon configuration is implemented in the class <code class="ph codeph">org.dita.dost.module.XsltModule</code>,
which backs the <code class="keyword markupname xmlelement">&lt;pipeline&gt;</code>/<code class="keyword markupname xmlelement">&lt;xslt&gt;</code> element.</p>
<p class="p"> </p>
</div>
<nav role="navigation" class="related-links"><ul class="ullinks"><li class="link ulchildlink"><strong><a href="../topics/implement-saxon-extension-functions.html">Implementing Saxon extension functions</a></strong><br>Plug-ins can contribute Saxon extension functions for use in XSLT transformations run by DITA Open Toolkit.</li><li class="link ulchildlink"><strong><a href="../topics/implement-saxon-collation-uri-resolvers.html">Implementing custom Saxon collation URI resolvers</a></strong><br>Plug-ins can provide custom URI resolvers that provide collators for specific collation URIs.</li></ul><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/plugin-use-cases.html" title="Plug-ins allow you to extend the functionality of DITA-OT. This might entail adding support for specialized document types, integrating processing overrides, or defining new output transformations.">Plug-in use cases</a></div></div></nav></article></main></body></html>

48
dita-ot-3.6/doc/topics/implement-saxon-extension-functions.html Normal file
View file

@ -0,0 +1,48 @@
<!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="Plug-ins can contribute Saxon extension functions for use in XSLT transformations run by DITA Open Toolkit."><meta name="keywords" content="Saxon, service, Ant, jar, XSLT, Saxon, Java, extension functions"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Implementing Saxon extension functions</title></head><body id="implement-saxon-extension-functions"><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><ul><li><a href="../topics/plugin-set-parameters.html">Setting parameters</a></li><li><a href="../topics/plugin-anttarget.html">Adding a new Ant target</a></li><li><a href="../topics/plugin-antpreprocess.html">Adding a pre-processing step</a></li><li><a href="../topics/plugin-newtranstype.html">Adding a new output format</a></li><li><a href="../topics/plugin-xsltparams.html">Adding new parameters</a></li><li><a href="../topics/plugin-overridestyle.html">Overriding XSLT steps</a></li><li><a href="../topics/plugin-javalib.html">Adding a Java library</a></li><li><a href="../topics/plugin-messages.html">Adding new messages</a></li><li><a href="../topics/plugin-newextensions.html">New extension points</a></li><li><a href="../topics/plugin-xmlcatalog.html">Extending an XML catalog file</a></li><li><a href="../topics/plugin-rewrite-rules.html">Rewriting file names</a></li><li><a href="../topics/implement-saxon-customizations.html">Saxon customizations</a><ul><li class="active"><a href="../topics/implement-saxon-extension-functions.html">Saxon extensions</a></li><li><a href="../topics/implement-saxon-collation-uri-resolvers.html">Custom collation URI resolvers</a></li></ul></li></ul></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></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">Implementing Saxon extension functions</h1>
<div class="body"><p class="shortdesc">Plug-ins can contribute Saxon extension functions for use in XSLT transformations run by DITA Open
Toolkit.</p>
<p class="p">Starting with Saxon 9.2, the mechanism for implementing extension functions has changed such that Saxon HE, in
particular, can no longer use the older “reflexive” mechanism for finding Java extension functions using a magic
URL. Instead, you implement extension functions and then register them directly on the Saxon Configuration object.
DITA-OT provides a dynamic mechanism to perform this registration for plug-in-provided extension functions.</p>
<div class="p">To implement extension functions, you must do the following:
<ol class="ol">
<li class="li">Add your plug-in’s JAR file in the DITA-OT class path as described in
<a class="xref" href="plugin-javalib.html" title="You can use the dita.conductor.lib.import extension point to add an additional Java library to the DITA-OT classpath parameter.">Adding a Java library to the classpath</a>.</li>
<li class="li">For each function, implement a class that extends
<code class="ph codeph">net.sf.saxon.lib.ExtensionFunctionDefinition</code>. This class provides the namespace name and
function name for the function as well as details about its arguments and so on. See
<a class="xref" href="http://www.saxonica.com/html/documentation9.8/extensibility/integratedfunctions" target="_blank" rel="external noopener">Integrated extension functions</a> in the Saxon documentation.</li>
<li class="li">Include a file named <span class="ph filepath">net.sf.saxon.lib.ExtensionFunctionDefinition</span> in the directory
<span class="ph filepath">META-INF/services</span> in the compiled JAR that your plug-in provides. Each line of the file
must be the name of a class that implements <code class="ph codeph">net.sf.saxon.lib.ExtensionFunctionDefinition</code>: <pre class="pre codeblock"><code>com.example.saxon.functions.Add
com.example.saxon.functions.Substract</code></pre>
<div class="p">You can create the file using <code class="keyword markupname xmlelement">&lt;service&gt;</code> elements in an Ant
<code class="keyword markupname xmlelement">&lt;jar&gt;</code>
task:<pre class="pre codeblock language-xml"><code>&lt;jar destfile="${basedir}/target/lib/example-saxon.jar"&gt;
⋮
&lt;service type="net.sf.saxon.lib.ExtensionFunctionDefinition"&gt;
&lt;provider classname="com.example.saxon.functions.Add"/&gt;
&lt;provider classname="com.example.saxon.functions.Subtract"/&gt;
&lt;/service&gt;
⋮
&lt;/jar&gt;</code></pre></div></li>
<li class="li">In your XSLT transformations, declare the namespace the functions are bound
to:<pre class="pre codeblock language-xml"><code>&lt;xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
<strong class="ph b">xmlns:eg="http://example.com/saxon-extensions"</strong>
version="2.0"&gt;</code></pre></li>
</ol></div>
<div class="p">You should then be able to use the extension functions as you would any other
function:<pre class="pre codeblock language-xml"><code>&lt;xsl:variable name="test" select="<strong class="ph b">eg:add(1, 2)</strong>"/&gt;</code></pre></div>
</div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/implement-saxon-customizations.html" title="Plug-ins can contribute XSLT extension functions and collation URI resolvers. These customizations are automatically configured to work with Saxon when transformations are run using the DITA-OT pipeline task with custom XSLT.">Adding Saxon customizations</a></div></div></nav></article></main></body></html>

31
dita-ot-3.6/doc/topics/increasing-the-jvm.html Normal file
View file

@ -0,0 +1,31 @@
<!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 are working with large documents with extensive metadata or key references, you will need to increase the memory allocation for the Java process. You can do this from the command-line prompt for a specific session, or you can increase the value of the ANT_OPTS environment variable."><meta name="keywords" content="macOS, increase Java memory, Linux, Windows, command line, operating system, Linux, macOS, Windows, Java, memory, ANT_OPTS, metadata, processing time, effect on"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Increasing Java memory allocation</title></head><body id="t-increasing-the-JVM"><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></li><li><a href="../topics/troubleshooting-overview.html">Troubleshooting</a><ul><li><a href="../topics/logging.html">Logging</a></li><li><a href="../topics/enabling-debug-mode.html">Enabling debug mode</a></li><li><a href="../topics/error-messages.html">DITA-OT error messages</a></li><li><a href="../topics/other-errors.html">Other error messages</a></li><li><a href="../topics/dita-command-help.html">Command line help</a></li><li class="active"><a href="../topics/increasing-the-jvm.html">Increasing Java memory</a></li><li><a href="../topics/reducing-processing-time.html">Speeding up builds</a></li></ul></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">Increasing Java memory allocation</h1>
<div class="body taskbody"><p class="shortdesc">If you are working with large documents with extensive metadata or key references, you will need to
increase the memory allocation for the Java process. You can do this from the command-line prompt for a specific
session, or you can increase the value of the <code class="ph codeph">ANT_OPTS</code> environment variable.</p>
<section><div class="tasklabel"><h2 class="sectiontitle tasklabel">Procedure</h2></div><ul class="ul steps-unordered"><li class="li step stepexpand">
<span class="ph cmd">To change the value for a specific session, from the command prompt, issue the following command:</span>
<table border="1" frame="hsides" rules="rows" cellpadding="4" cellspacing="0" summary="" class="simpletable choicetable choicetableborder multi-platform"><colgroup><col style="width:50%"><col style="width:50%"></colgroup><thead><tr class="sthead chhead"><th scope="col" class="stentry choptionhd" style="vertical-align:bottom;text-align:left;">Platform</th><th scope="col" class="stentry chdeschd" style="vertical-align:bottom;text-align:left;">Command</th></tr></thead><tbody><tr class="strow chrow">
<th style="vertical-align:top;" scope="row" class="stentry choption">Linux or macOS&nbsp;</th>
<td style="vertical-align:top;" class="stentry chdesc"><code class="ph codeph">export ANT_OPTS=$ANT_OPTS -Xmx<var class="keyword varname">1024</var>M</code></td>
</tr><tr class="strow chrow">
<th style="vertical-align:top;" scope="row" class="stentry choption">Windows</th>
<td style="vertical-align:top;" class="stentry chdesc"><code class="ph codeph">set ANT_OPTS=%ANT_OPTS% -Xmx<var class="keyword varname">1024</var>M</code></td>
</tr></tbody></table>
<div class="itemgroup info">
<p class="p">This increases the JVM memory allocation to 1024 megabytes. The amount of memory which can be allocated is
limited by available system memory and the operating system.</p></div>
</li><li class="li step stepexpand">
<span class="ph cmd">To persistently change the value, change the value allocated to the <code class="ph codeph">ANT_OPTS</code> environment
variable on your system.</span>
</li></ul></section>
</div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/troubleshooting-overview.html" title="This section contains information about problems that you might encounter and how to resolve them.">Error messages and troubleshooting</a></div></div></nav></article></main></body></html>

11
dita-ot-3.6/doc/topics/input-formats.html Normal file
View file

@ -0,0 +1,11 @@
<!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="In addition to standard DITA XML, DITA-OT supports several alternative input formats, including Markdown and the proposed XDITA, MDITA and HDITA authoring formats currently in development for Lightweight DITA."><meta name="keywords" content="Lightweight DITA, LwDITA, MDITA, XDITA, HDITA, authoring formats, input formats, formats, transformations"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Authoring formats</title></head><body id="alternative-authoring-formats"><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 class="active"><a href="../topics/input-formats.html">Authoring formats</a><ul><li><a href="../topics/dita-xml-input.html">Standard DITA XML</a></li><li><a href="../topics/markdown-input.html">Markdown content</a></li><li><a href="../topics/lwdita-input.html">Lightweight DITA</a></li><li><a href="../topics/markdown-dita-syntax-reference.html">Markdown DITA syntax</a></li></ul></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></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">Authoring formats</h1>
<p class="shortdesc">In addition to standard DITA XML, DITA-OT supports several alternative input formats, including Markdown
and the proposed XDITA, MDITA and HDITA authoring formats currently in development for Lightweight DITA.</p>
<nav role="navigation" class="related-links"><ul class="ullinks"><li class="link ulchildlink"><strong><a href="../topics/dita-xml-input.html">Standard DITA XML</a></strong><br>DITA Open Toolkit supports all released versions of the OASIS DITA specification, including 1.0, 1.1, 1.2, and 1.3. As of release <span class="keyword">3.6</span>, DITA-OT also provides an initial preview of features for the latest draft of the upcoming DITA 2.0 standard.</li><li class="link ulchildlink"><strong><a href="../topics/markdown-input.html">Markdown content</a></strong><br> <a class="xref" href="https://daringfireball.net/projects/markdown/" target="_blank" rel="external noopener">Markdown</a> is a lightweight markup language that allows you to write using an easy-to-read plain text format and convert to structurally valid markup as necessary.</li><li class="link ulchildlink"><strong><a href="../topics/lwdita-input.html">Preview support for Lightweight DITA</a></strong><br>DITA-OT provides preview support for the authoring formats proposed for <a class="xref" href="http://docs.oasis-open.org/dita/LwDITA/v1.0/cn01/LwDITA-v1.0-cn01.pdf" target="_blank" rel="external noopener">Lightweight DITA</a>, or “<dfn class="term">LwDITA</dfn>”. The XDITA, MDITA and HDITA formats are alternative representations of DITA content in XML, Markdown and HTML5.</li><li class="link ulchildlink"><strong><a href="../topics/markdown-dita-syntax-reference.html">Markdown DITA syntax reference</a></strong><br>Markdown DITA uses <a class="xref" href="http://commonmark.org" target="_blank" rel="external noopener">CommonMark</a> as the underlying markup language.</li></ul></nav></article></main></body></html>

59
dita-ot-3.6/doc/topics/installing-client.html Normal file
View file

@ -0,0 +1,59 @@
<!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="The DITA-OT distribution package can be installed on Linux, macOS, and Windows. It contains everything that you need to run the toolkit except for Java."><meta name="keywords" content="macOS, installing DITA-OT, Linux, Windows, command, dita, installing, installing, DITA-OT, Java, Java Development Kit (JDK), Java Runtime Environment (JRE)"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Installing DITA Open Toolkit</title></head><body id="installing-client"><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 class="active"><a href="../topics/installing-client.html">Installing DITA-OT</a><ul><li><a href="../topics/prerequisite-software.html">Prerequisite software</a></li><li><a href="../topics/determining-version-of-ditaot.html">Checking the version</a></li><li><a href="../topics/first-build-using-dita-command.html">Building output</a></li><li><a href="../topics/installing-via-homebrew.html">Installing via Homebrew</a></li></ul></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></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">Installing DITA Open Toolkit</h1>
<div class="body taskbody"><p class="shortdesc">The DITA-OT distribution package can be installed on Linux, macOS, and Windows. It
contains everything that you need to run the toolkit except for Java.</p>
<section class="section prereq"><div class="tasklabel"><h2 class="sectiontitle tasklabel">Before you begin</h2></div>
<ul class="ul">
<li class="li">
<p class="p">Ensure that you have a Java Runtime Environment (JRE) or Java Development Kit (JDK).</p>
<div class="p">DITA-OT is designed to run on Java version <span class="keyword">8u101</span> or later and
built and tested with the Open Java Development Kit (OpenJDK). Compatible Java distributions are available from
multiple sources:
<ul class="ul">
<li class="li">You can download the Oracle JRE or JDK from
<a class="xref" href="http://www.oracle.com/technetwork/java/javase/downloads" target="_blank" rel="external noopener">oracle.com/technetwork/java</a> under commercial license.</li>
<li class="li">OpenJDK is a free open-source implementation of Java available from
<a class="xref" href="https://adoptopenjdk.net" target="_blank" rel="external noopener">adoptopenjdk.net</a>.</li>
<li class="li">Free OpenJDK distributions are also available from other vendors, including
<a class="xref" href="https://aws.amazon.com/corretto/" target="_blank" rel="external noopener">Amazon Corretto</a>,
<a class="xref" href="https://www.azul.com/downloads/zulu/" target="_blank" rel="external noopener">Azul Zulu</a>, and
<a class="xref" href="https://developers.redhat.com/products/openjdk/download" target="_blank" rel="external noopener">Red Hat</a>.</li>
</ul>
</div></li>
<li class="li">If you want to generate HTML Help, ensure that you have HTML Help
Workshop installed.
<p class="p">You can download the Help Workshop from
<a class="xref" href="http://msdn.microsoft.com/en-us/library/windows/desktop/ms669985%28v=vs.85%29.aspx" target="_blank" rel="external noopener">msdn.microsoft.com</a>.</p></li>
</ul>
</section>
<section><div class="tasklabel"><h2 class="sectiontitle tasklabel">Procedure</h2></div><ol class="ol steps"><li class="li step stepexpand">
<span class="ph cmd"><span class="ph">Download the <span class="ph filepath">dita-ot-<span class="keyword">3.6</span>.zip</span>
package from the project website at
<a class="xref" href="https://www.dita-ot.org/download" target="_blank" rel="external noopener">dita-ot.org/download</a>.</span></span>
</li><li class="li step stepexpand">
<span class="ph cmd">Extract the contents of the package to the directory where you want to install DITA-OT.</span>
</li><li class="li step stepexpand">
<span class="ph cmd">Add the absolute path for the <span class="ph filepath">bin</span> folder of the DITA-OT installation directory to the
<a class="xref" href="https://en.wikipedia.org/wiki/PATH_(variable)" target="_blank" rel="external noopener">PATH environment variable</a>.</span>
<div class="itemgroup stepresult">
<div class="note tip note_tip" id="installing-client__dita-in-path"><span class="note__title">Tip:</span> This defines the necessary environment variable that allows the
<span class="keyword cmdname">dita</span> command to be run from any location on the file system without typing the path to
the command.
</div>
</div>
</li></ol></section>
</div>
<nav role="navigation" class="related-links"><ul class="ullinks"><li class="link ulchildlink"><strong><a href="../topics/prerequisite-software.html">Prerequisite software</a></strong><br>The prerequisite software that DITA-OT requires depends on the types of transformations that you want to use.</li><li class="link ulchildlink"><strong><a href="../topics/determining-version-of-ditaot.html">Checking the DITA-OT version number</a></strong><br>You can determine the DITA Open Toolkit version number from a command prompt.</li><li class="link ulchildlink"><strong><a href="../topics/first-build-using-dita-command.html">Building output using the dita command</a></strong><br>You can generate output using the <span class="keyword cmdname">dita</span> command-line tool. Build parameters can be specified on the command line or with <span class="ph filepath">.properties</span> files.</li><li class="link ulchildlink"><strong><a href="../topics/installing-via-homebrew.html">Installing on macOS via Homebrew</a></strong><br>An alternative installation method can be used to install DITA-OT on macOS via <a class="xref" href="https://brew.sh" target="_blank" rel="external noopener">Homebrew</a>, the platform’s most popular open-source package manager.</li></ul></nav></article></main></body></html>

64
dita-ot-3.6/doc/topics/installing-via-homebrew.html Normal file
View file

@ -0,0 +1,64 @@
<!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="An alternative installation method can be used to install DITA-OT on macOS via Homebrew, the platform’s most popular open-source package manager."><meta name="keywords" content="macOS, command, dita, Homebrew, installing"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Installing on macOS via Homebrew</title></head><body id="installing-via-homebrew"><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><ul><li><a href="../topics/prerequisite-software.html">Prerequisite software</a></li><li><a href="../topics/determining-version-of-ditaot.html">Checking the version</a></li><li><a href="../topics/first-build-using-dita-command.html">Building output</a></li><li class="active"><a href="../topics/installing-via-homebrew.html">Installing via Homebrew</a></li></ul></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></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">Installing on macOS via Homebrew</h1>
<div class="body taskbody"><p class="shortdesc">An alternative installation method can be used to install DITA-OT on macOS via
<a class="xref" href="https://brew.sh" target="_blank" rel="external noopener">Homebrew</a>, the platform’s most popular open-source package manager.</p>
<section class="section prereq"><div class="tasklabel"><h2 class="sectiontitle tasklabel">Before you begin</h2></div>
<p class="p">The steps below assume you have already installed
<a class="xref" href="https://brew.sh" target="_blank" rel="external noopener">Homebrew</a> according to the instructions at
<a class="xref" href="https://brew.sh" target="_blank" rel="external noopener">brew.sh</a>.</p>
<div class="note tip note_tip"><span class="note__title">Tip:</span> Verify that your
<a class="xref" href="https://en.wikipedia.org/wiki/PATH_(variable)" target="_blank" rel="external noopener">PATH environment variable</a> begins with <span class="ph filepath">/usr/local/bin</span> to ensure that Homebrew-installed software
takes precedence over any programs of the same name elsewhere on the system.</div>
</section>
<section><div class="tasklabel"><h2 class="sectiontitle tasklabel">Procedure</h2></div><ol class="ol steps"><li class="li step stepexpand">
<span class="ph cmd">Update Homebrew to make sure the latest package formulas are available on your system:</span>
<div class="itemgroup stepxmp"><pre class="pre codeblock syntax-bash"><code>$ <span class="keyword cmdname">brew update</span>
Already up-to-date.</code></pre></div>
<div class="itemgroup stepresult">
<p class="p">Homebrew responds with a list of any new or updated formulæ.</p></div>
</li><li class="li step stepexpand"><strong>Optional: </strong>
<span class="ph cmd">Check the version of DITA-OT that is available from Homebrew:</span>
<div class="itemgroup stepxmp"><pre class="pre codeblock syntax-bash"><code>$ <span class="keyword cmdname">brew info dita-ot</span>
<samp class="ph systemoutput sysout">dita-ot: stable <span class="keyword">3.6</span>
DITA Open Toolkit is an implementation of the OASIS DITA specification
https://www.dita-ot.org/
/usr/local/Cellar/dita-ot/<span class="keyword">3.6</span> (<var class="keyword varname">number of files</var>, <var class="keyword varname">package size</var>) *
Built from source on <var class="keyword varname">YYYY-MM-DD</var> at <var class="keyword varname">hh:mm:ss</var>
From: https://github.com/Homebrew/homebrew-core/blob/master/Formula/dita-ot.rb
==&gt; Requirements
Required: java &gt;= 1.8 ✔</samp>
</code></pre></div>
<div class="itemgroup stepresult">
<p class="p">The version of the DITA-OT formula is shown, along with basic information on the package.</p></div>
</li><li class="li step stepexpand">
<span class="ph cmd">Install the <code class="ph codeph">dita-ot</code> package:</span>
<div class="itemgroup stepxmp"><pre class="pre codeblock syntax-bash"><code>$ <span class="keyword cmdname">brew install dita-ot</span>
<samp class="ph systemoutput sysout">Downloading…</samp></code></pre></div>
<div class="itemgroup stepresult">
<p class="p">Homebrew will automatically download the latest version of the toolkit, install it in a subfolder of the
local package Cellar and symlink the <span class="keyword cmdname">dita</span> command to
<span class="ph filepath">/usr/local/bin/dita</span>.</p></div>
</li><li class="li step stepexpand"><strong>Optional: </strong>
<span class="ph cmd">Verify the installation:</span>
<div class="itemgroup stepxmp"><pre class="pre codeblock syntax-bash"><code>$ <span class="keyword cmdname">which dita</span>
<samp class="ph systemoutput sysout">/usr/local/bin/dita</samp></code></pre></div>
<div class="itemgroup stepresult">
<p class="p">The response confirms that the system will use the Homebrew-installed version of DITA-OT.</p></div>
</li><li class="li step stepexpand"><strong>Optional: </strong>
<span class="ph cmd">Check the DITA-OT version number:</span>
<div class="itemgroup stepxmp"><pre class="pre codeblock syntax-bash"><code>$ <span class="keyword cmdname">dita</span> <span class="keyword parmname">--version</span>
<samp class="ph systemoutput sysout">DITA-OT version <span class="keyword">3.6</span></samp></code></pre></div>
<div class="itemgroup stepresult">The DITA-OT version number appears on the console.</div>
</li></ol></section>
<section class="section result"><div class="tasklabel"><h2 class="sectiontitle tasklabel">Results</h2></div>
<p class="p">You can now run the <span class="keyword cmdname">dita</span> command to transform DITA content.</p></section>
</div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/installing-client.html" title="The DITA-OT distribution package can be installed on Linux, macOS, and Windows. It contains everything that you need to run the toolkit except for Java.">Installing DITA Open Toolkit</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/2018/dita-ot_day.html#installing_DITA-OT_on_macOS_via_homebrew" target="_blank" rel="external noopener" title="A new alternative installation method can now be used to install DITA-OT on macOS via the platform's most popular open-source package manager. This talk explains the benefits of this approach, highlights key differences to the default installation via .zip archive and demonstrates the new installation process.">Installing DITA-OT on macOS via Homebrew</a></li></ul></div></nav></article></main></body></html>

103
dita-ot-3.6/doc/topics/logging.html Normal file
View file

@ -0,0 +1,103 @@
<!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="When you run DITA-OT, key information is logged on the screen. This information can also be written to a log file. If you encounter a problem, you can analyze this information to determine the source of the problem and then take action to resolve it."><meta name="keywords" content="Apache FOP, log files, command, dita, logging, verbose logging, Ant, debugging, Java"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Logging build information</title></head><body id="loghandling"><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></li><li><a href="../topics/troubleshooting-overview.html">Troubleshooting</a><ul><li class="active"><a href="../topics/logging.html">Logging</a></li><li><a href="../topics/enabling-debug-mode.html">Enabling debug mode</a></li><li><a href="../topics/error-messages.html">DITA-OT error messages</a></li><li><a href="../topics/other-errors.html">Other error messages</a></li><li><a href="../topics/dita-command-help.html">Command line help</a></li><li><a href="../topics/increasing-the-jvm.html">Increasing Java memory</a></li><li><a href="../topics/reducing-processing-time.html">Speeding up builds</a></li></ul></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">Logging build information</h1>
<div class="body conbody"><p class="shortdesc">When you run DITA-OT, key information is logged on the screen. This information can also be written to a
log file. If you encounter a problem, you can analyze this information to determine the source of the problem and
then take action to resolve it.</p>
<p class="p">The logging behavior varies depending on whether you use the <span class="keyword cmdname">dita</span> command or Ant to invoke a
toolkit build.</p>
<dl class="dl">
<dt class="dt dlterm"><span class="keyword cmdname">dita</span> command</dt>
<dd class="dd">
<p class="p">By default, only warning and error messages are written to the screen.</p>
<ul class="ul">
<li class="li">
<p class="p">For more information, enable verbose logging with <span class="keyword cmdname">dita</span>
<span class="keyword parmname">--verbose</span>.</p>
<p class="p">Verbose logging prints additional information to the console, including directory settings, effective
values for Ant properties, input/output files, and informational messages to assist in
troubleshooting.</p></li>
<li class="li">
<p class="p">To enable debug logging, use <span class="keyword cmdname">dita</span>
<span class="keyword parmname">--debug</span>.</p>
<p class="p">Debug logging prints considerably more additional information. The debug log includes all information
from the verbose log, plus details on Java classes, additional Ant properties and overrides,
preprocessing filters, parameters, and stages, and the complete build sequence.</p>
<div class="note attention note_attention"><span class="note__title">Attention:</span> Debug logging requires additional resources and can slow down the build process, so
it should only be enabled when further details are required to diagnose problems.</div>
</li>
<li class="li">
<p class="p">To write the log to a file, use <span class="keyword cmdname">dita</span>
<span class="keyword parmname">--logfile</span>=<var class="keyword varname">file</var> and specify the path to the log file.</p>
<p class="p">Unless an absolute path is specified, the value will be interpreted relative to the current
directory.</p></li>
</ul></dd>
<dt class="dt dlterm">Ant</dt>
<dd class="dd">By default, status information is written to the screen. If you issue the <span class="keyword parmname">-l</span> parameter,
the build runs silently and the information is written to a log file with the name and location that you
specified.</dd>
</dl>
<section class="section"><h2 class="title sectiontitle">Using other Ant loggers</h2>
<p class="p">You also can use other Ant loggers; see
<a class="xref" href="https://ant.apache.org/manual/listeners.html" target="_blank" rel="external noopener">Listeners &amp;
Loggers</a> in the Ant documentation for more information.</p>
<p class="p">For example, you can use the <strong class="ph b">AnsiColorLogger</strong> to colorize the messages written on the screen.</p>
<dl class="dl">
<dt class="dt dlterm"><span class="keyword cmdname">dita</span> command</dt>
<dd class="dd">
<p class="p">To use a custom Ant logger with the <span class="keyword cmdname">dita</span> command, add the logger to the
<code class="ph codeph">ANT_ARGS</code> environment variable by calling the following command before calling the
<span class="keyword cmdname">dita</span> command:</p>
<pre class="pre codeblock syntax-bash"><code>export ANT_ARGS="-logger org.apache.tools.ant.listener.AnsiColorLogger"</code></pre>
<p class="p">Now you will get colorized messages when the <span class="keyword cmdname">dita</span> command runs.</p>
<div class="note tip note_tip"><span class="note__title">Tip:</span> Environment variables can also be set permanently. See
<a class="xref" href="https://www.java.com/en/download/help/path.xml" target="_blank" rel="external noopener">How do I set or
change the PATH system variable?</a> for information on how to set the
<a class="xref" href="https://en.wikipedia.org/wiki/PATH_(variable)" target="_blank" rel="external noopener">PATH environment variable</a>. You can set the <code class="ph codeph">ANT_ARGS</code> environment variable in the same
way.</div>
</dd>
<dt class="dt dlterm">Ant</dt>
<dd class="dd">
<p class="p">If you prefer to launch DITA-OT directly from Ant, you can also add the logger to the
<code class="ph codeph">ANT_ARGS</code> environment variable, as explained above. You can also set the logger with the
<code class="ph codeph">-logger</code> parameter when calling Ant.</p>
<pre class="pre codeblock syntax-bash"><code>ant -logger org.apache.tools.ant.listener.AnsiColorLogger</code></pre>
</dd>
</dl>
</section>
<section class="section"><h2 class="title sectiontitle">FOP debug logging</h2>
<p class="p">In PDF processing with Apache™ FOP, DITA-OT uses the Simple Logging
Facade for Java (SLF4J) for better control and formatting of FOP log messages. To reduce noise on the console,
all FOP messages are set to the Info level and hidden by default.</p>
<p class="p">To enable debug logging, modify the <span class="ph filepath">config/logback.xml</span> file or add your own
<span class="ph filepath">logback.xml</span> to the classpath with a higher priority to override the default settings. For
more information, see the
<a class="xref" href="https://logback.qos.ch/manual/configuration.html" target="_blank" rel="external noopener">Logback
configuration documentation</a>.</p>
<div class="note attention note_attention"><span class="note__title">Attention:</span> Enabling FOP debug logging will dramatically increase the size of generated log
files.</div>
</section>
</div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/troubleshooting-overview.html" title="This section contains information about problems that you might encounter and how to resolve them.">Error messages and troubleshooting</a></div></div></nav></article></main></body></html>

94
dita-ot-3.6/doc/topics/lwdita-input.html Normal file
View file

@ -0,0 +1,94 @@
<!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 provides preview support for the authoring formats proposed for Lightweight DITA, or “LwDITA”. The XDITA, MDITA and HDITA formats are alternative representations of DITA content in XML, Markdown and HTML5."><meta name="keywords" content=", topicref, format, authoring formats, Lightweight DITA, metadata, DITA 1.3, converting lightweight formats to DITA"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Preview support for Lightweight DITA</title></head><body id="lwdita-input"><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><ul><li><a href="../topics/dita-xml-input.html">Standard DITA XML</a></li><li><a href="../topics/markdown-input.html">Markdown content</a></li><li class="active"><a href="../topics/lwdita-input.html">Lightweight DITA</a></li><li><a href="../topics/markdown-dita-syntax-reference.html">Markdown DITA syntax</a></li></ul></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></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">Preview support for Lightweight DITA</h1>
<div class="body"><p class="shortdesc">DITA-OT provides preview support for the authoring formats proposed for
<a class="xref" href="http://docs.oasis-open.org/dita/LwDITA/v1.0/cn01/LwDITA-v1.0-cn01.pdf" target="_blank" rel="external noopener">Lightweight DITA</a>, or “<dfn class="term">LwDITA</dfn>”. The XDITA, MDITA and HDITA formats are alternative
representations of DITA content in XML, Markdown and HTML5.</p>
<div class="note attention note_attention"><span class="note__title">Attention:</span> Since
<a class="xref" href="http://docs.oasis-open.org/dita/LwDITA/v1.0/cn01/LwDITA-v1.0-cn01.pdf" target="_blank" rel="external noopener">Lightweight DITA</a> has not yet been released as a formal specification, the implementation for XDITA, MDITA
and HDITA authoring formats is subject to change. Future versions of DITA Open Toolkit will be updated as LwDITA
evolves.</div>
<section class="section"><h2 class="title sectiontitle">XDITA</h2>
<p class="p">XDITA is the LwDITA authoring format that uses XML to structure information. XDITA is a subset of DITA, with
new multimedia element types added to support interoperability with HTML5. XDITA is designed for users who want
to write DITA content but who do not want (or need) the full power of DITA.</p>
<p class="p">The XDITA parser included in the <code class="ph codeph">org.lwdita</code> plug-in provides preliminary support for XDITA
maps and XDITA topics.</p>
<p class="p">To apply XDITA-specific processing to topics in an XDITA map or a full DITA 1.3 map, set the
<code class="keyword markupname xmlatt">@format</code> attribute on a <code class="keyword markupname xmlelement">&lt;topicref&gt;</code> to <code class="ph codeph">xdita</code>:</p>
<div class="p">
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;map&gt;
&lt;topicref href="xdita-topic.xml" <strong class="ph b">format="xdita"</strong>/&gt;
&lt;/map&gt;</code></pre>
</div>
<div class="note tip note_tip"><span class="note__title">Tip:</span> For examples of cross-format content sharing between topics in XDITA, HDITA, extended-profile
MDITA, and DITA 1.3, see the LwDITA sample files in the DITA-OT installation directory under
<span class="ph filepath">plugins/org.oasis-open.xdita.v0_2_2/samples</span>.</div>
</section>
<section class="section"><h2 class="title sectiontitle">MDITA</h2>
<p class="p">MDITA is the LwDITA authoring format based on Markdown. It is designed for users who want to write structured
content with the minimum of overhead, but who also want to take advantage of the reuse mechanisms associated
with the DITA standard and the multi-channel publishing afforded by standard DITA tooling.</p>
<p class="p">Recent proposals for LwDITA include two profiles for authoring MDITA topics:</p>
<ul class="ul">
<li class="li">The “<dfn class="term">Core profile</dfn>” is based on
<a class="xref" href="https://github.github.com/gfm/" target="_blank" rel="external noopener">GitHub-Flavored Markdown</a> and includes elements that are common to many other Markdown implementations.</li>
<li class="li">The “<dfn class="term">Extended profile</dfn>” borrows additional features from other flavors of Markdown to represent
a broader range of DITA content with existing plain-text syntax conventions.</li>
</ul>
<p class="p">The Markdown DITA parser included in the <code class="ph codeph">org.lwdita</code> plug-in provides preliminary support for
these profiles and additional Markdown constructs as described in the syntax reference.</p>
<p class="p">To apply LwDITA-specific processing to Markdown topics, set the <code class="keyword markupname xmlatt">@format</code> attribute to
<code class="ph codeph">mdita</code>:</p>
<div class="p">
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;map&gt;
&lt;topicref href="mdita-topic.md" <strong class="ph b">format="mdita"</strong>/&gt;
&lt;/map&gt;</code></pre>
</div>
<p class="p">In this case, the first paragraph in the topic will be treated as a short description, for example, and
additional metadata can be specified for the topic via a YAML front matter block.</p>
<div class="note note note_note"><span class="note__title">Note:</span> Setting the <code class="keyword markupname xmlatt">@format</code> attribute to <code class="ph codeph">mdita</code> triggers stricter parsing than the
more lenient document parsing approach that is applied to <code class="ph codeph">markdown</code> documents.</div>
<div class="note attention note_attention"><span class="note__title">Attention:</span> The MDITA map format is not yet supported. To include Markdown content in publications, use
an XDITA map or a DITA 1.3 map.</div>
</section>
<section class="section"><h2 class="title sectiontitle">HDITA</h2>
<p class="p">HDITA is the LwDITA authoring format based on HTML5, which is intended to support structured content authoring
with tools designed for HTML authoring. HDITA also uses custom data attributes to provide interoperability with
DITA.</p>
<p class="p">The HDITA parser included in the <code class="ph codeph">org.lwdita</code> plug-in provides preliminary support for these
constructs.</p>
<p class="p">To apply LwDITA-specific processing to HTML topics, set the <code class="keyword markupname xmlatt">@format</code> attribute to
<code class="ph codeph">hdita</code>:</p>
<div class="p">
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;map&gt;
&lt;topicref href="hdita-topic.html" <strong class="ph b">format="hdita"</strong>/&gt;
&lt;/map&gt;</code></pre>
</div>
<div class="note attention note_attention"><span class="note__title">Attention:</span> The HDITA map format is not yet supported. To include HDITA content, use an XDITA map or a
DITA 1.3 map.</div>
</section>
<section class="section"><h2 class="title sectiontitle">Converting lightweight formats to DITA XML</h2>
<p class="p">When you add LwDITA topics to a DITA publication, the content is temporarily converted to DITA in the
background when generating other output formats like HTML or PDF, but the source files remain unchanged.</p>
<p class="p">If you prefer to maintain this content in DITA in the future, you can generate DITA output by passing the
<span class="keyword parmname">--format</span>=<span class="keyword option">dita</span> option on the command line.</p>
<p class="p">This converts all input files (both LwDITA formats and DITA XML) to
<a class="xref" href="dita2dita.html" title="The dita transformation generates normalized topics and maps from DITA input. The normalized output includes the results of DITA Open Toolkit pre-processing operations, which resolve map references, keys, content references, code references and push metadata back and forth between maps and topics.">Normalized DITA</a>. You can then copy the generated DITA files from the output
folder to your project and replace references to the lightweight topics with their DITA equivalents.</p>
</section>
</div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/input-formats.html" title="In addition to standard DITA XML, DITA-OT supports several alternative input formats, including Markdown and the proposed XDITA, MDITA and HDITA authoring formats currently in development for Lightweight DITA.">Authoring formats</a></div></div><div class="linklist relinfo"><strong>Related information</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/dita-xml-input.html" title="DITA Open Toolkit supports all released versions of the OASIS DITA specification, including 1.0, 1.1, 1.2, and 1.3. As of release 3.6, DITA-OT also provides an initial preview of features for the latest draft of the upcoming DITA 2.0 standard.">Standard DITA XML</a></li><li class="linklist"><a class="link" href="../topics/markdown-input.html" title="Markdown is a lightweight markup language that allows you to write using an easy-to-read plain text format and convert to structurally valid markup as necessary.">Markdown content</a></li><li class="linklist"><a class="link" href="../topics/markdown-dita-syntax-reference.html" title="Markdown DITA uses CommonMark as the underlying markup language.">Markdown DITA syntax reference</a></li></ul></div></nav></article></main></body></html>

361
dita-ot-3.6/doc/topics/markdown-dita-syntax-reference.html Normal file
View file

@ -0,0 +1,361 @@
<!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="Markdown DITA uses CommonMark as the underlying markup language."><meta name="keywords" content="Pandoc, UTF, DITA, specializations, Markdown, CommonMark"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Markdown DITA syntax reference</title></head><body id="markdown-dita-syntax-reference"><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><ul><li><a href="../topics/dita-xml-input.html">Standard DITA XML</a></li><li><a href="../topics/markdown-input.html">Markdown content</a></li><li><a href="../topics/lwdita-input.html">Lightweight DITA</a></li><li class="active"><a href="../topics/markdown-dita-syntax-reference.html">Markdown DITA syntax</a></li></ul></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></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">Markdown DITA syntax reference</h1>
<div class="body"><p class="shortdesc">Markdown DITA uses
<a class="xref" href="http://commonmark.org" target="_blank" rel="external noopener">CommonMark</a> as the underlying markup language.</p>
<p class="p">Markdown DITA files must be UTF-8 encoded.</p>
<section class="section" id="markdown-dita-syntax-reference__titles-and-document-structure"><h2 class="title sectiontitle">Titles and document structure</h2>
<p class="p">Each header level will generate a topic and associated title:</p>
<pre class="pre codeblock language-markdown normalize-space show-line-numbers show-whitespace"><code># Topic title
## Nested topic title</code></pre>
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;topic id="topic_title"&gt;
&lt;title&gt;Topic title&lt;/title&gt;
&lt;topic id="nested_topic_title"&gt;
&lt;title&gt;Nested topic title&lt;/title&gt;
&lt;/topic&gt;
&lt;/topic&gt;</code></pre>
<p class="p">Pandoc
<a class="xref" href="http://pandoc.org/MANUAL.html#extension-header_attributes" target="_blank" rel="external noopener">header_attributes</a> can be used to define <code class="ph codeph">id</code> or
<code class="ph codeph">outputclass</code> attributes:</p>
<pre class="pre codeblock language-markdown normalize-space show-line-numbers show-whitespace"><code># Topic title {#carrot .juice}</code></pre>
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;topic id="carrot" outputclass="juice"&gt;
&lt;title&gt;Topic title&lt;/title&gt;</code></pre>
<p class="p">If topic ID is not defined using header_attributes, the ID is generated from title contents.</p>
<p class="p">Pandoc
<a class="xref" href="http://pandoc.org/MANUAL.html#extension-pandoc_title_block" target="_blank" rel="external noopener">pandoc_title_block</a>
extension can be used to group multiple level 1 headers under a common title:</p>
<pre class="pre codeblock language-markdown normalize-space show-line-numbers show-whitespace"><code>% Common title
# Topic title
# Second title</code></pre>
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;topic id="common_title"&gt;
&lt;title&gt;Common title&lt;/title&gt;
&lt;topic id="topic_title"&gt;
&lt;title&gt;Topic title&lt;/title&gt;
&lt;/topic&gt;
&lt;topic id="second_title"&gt;
&lt;title&gt;Second title&lt;/title&gt;
&lt;/topic&gt;
&lt;/topic&gt;</code></pre>
</section>
<section class="section" id="markdown-dita-syntax-reference__topic-content"><h2 class="title sectiontitle">Topic content</h2>
<p class="p">In LwDITA compatible documents (MDITA) the first paragraph is treated as a <code class="ph codeph">shortdesc</code> element.
In generic Markdown documents all paragraphs appear inside the <code class="ph codeph">body</code> element.</p></section>
<section class="section" id="markdown-dita-syntax-reference__specialization-types"><h2 class="title sectiontitle">Specialization types</h2>
<p class="p">The following class values in
<a class="xref" href="http://pandoc.org/MANUAL.html#extension-header_attributes" target="_blank" rel="external noopener">header_attributes</a> have a special meaning on level 1 headers:</p>
<ul class="ul">
<li class="li">
<code class="ph codeph">concept</code></li>
<li class="li">
<code class="ph codeph">task</code></li>
<li class="li">
<code class="ph codeph">reference</code></li>
</ul>
<p class="p">They can be used to change the Markdown DITA topic type to one of the built-in structural specialization
types.</p>
<pre class="pre codeblock language-markdown normalize-space show-line-numbers show-whitespace"><code># Task {.task}
Context
1. Command
Info.</code></pre>
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;task id="task"&gt;
&lt;title&gt;Task &lt;/title&gt;
&lt;taskbody&gt;
&lt;context&gt;
&lt;p&gt;Context&lt;/p&gt;
&lt;/context&gt;
&lt;steps&gt;
&lt;step&gt;
&lt;cmd&gt;Command&lt;/cmd&gt;
&lt;info&gt;
&lt;p&gt;Info.&lt;/p&gt;
&lt;/info&gt;
&lt;/step&gt;
&lt;/steps&gt;
&lt;/taskbody&gt;
&lt;/task&gt;</code></pre>
</section>
<section class="section" id="markdown-dita-syntax-reference__sections"><h2 class="title sectiontitle">Sections</h2>
<p class="p">The following class values in
<a class="xref" href="http://pandoc.org/MANUAL.html#extension-header_attributes" target="_blank" rel="external noopener">header_attributes</a> have a special meaning on header levels other than 1:</p>
<ul class="ul">
<li class="li">
<code class="ph codeph">section</code></li>
<li class="li">
<code class="ph codeph">example</code></li>
</ul>
<p class="p">They are used to generate
<a class="xref" href="http://docs.oasis-open.org/dita/v1.2/os/spec/langref/section.html" target="_blank" rel="external noopener"><code class="ph codeph">section</code></a> and
<a class="xref" href="http://docs.oasis-open.org/dita/v1.2/os/spec/langref/example.html" target="_blank" rel="external noopener"><code class="ph codeph">example</code></a> elements:</p>
<pre class="pre codeblock language-markdown normalize-space show-line-numbers show-whitespace"><code># Topic title
## Section title {.section}
## Example title {.example}</code></pre>
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;topic id="topic_title"&gt;
&lt;title&gt;Topic title&lt;/title&gt;
&lt;body&gt;
&lt;section&gt;
&lt;title&gt;Section title&lt;/title&gt;
&lt;/section&gt;
&lt;example&gt;
&lt;title&gt;Example title&lt;/title&gt;
&lt;/example&gt;
&lt;/body&gt;
&lt;/topic&gt;</code></pre>
</section>
<section class="section" id="markdown-dita-syntax-reference__hard-line-breaks"><h2 class="title sectiontitle">Hard line breaks</h2>
<p class="p">A line break that is preceded by two or more spaces is parsed as a hard line break. Because DITA doesn't have a
<code class="ph codeph">&lt;br&gt;</code> element for line break, hard line breaks are converted into
<code class="keyword markupname xmlpi">&lt;?linebreak?&gt;</code> processing instructions.</p>
<pre class="pre codeblock language-markdown normalize-space show-line-numbers show-whitespace"><code>foo··
baz</code></pre>
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;p&gt;foo&lt;?linebreak?&gt;baz&lt;/p&gt;</code></pre>
</section>
<section class="section" id="markdown-dita-syntax-reference__links"><h2 class="title sectiontitle">Links</h2>
<p class="p">The format of local link targets is detected based on file extension. The following extensions are treated as
DITA files:</p>
<table class="table table-hover frame-none"><caption></caption><colgroup><col><col></colgroup><thead class="thead">
<tr class="row">
<th class="entry colsep-0 rowsep-1" id="markdown-dita-syntax-reference__links__entry__1">extension</th>
<th class="entry colsep-0 rowsep-1" id="markdown-dita-syntax-reference__links__entry__2">format</th>
</tr>
</thead><tbody class="tbody">
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="markdown-dita-syntax-reference__links__entry__1"><code class="ph codeph">.dita</code></td>
<td class="entry colsep-0 rowsep-1" headers="markdown-dita-syntax-reference__links__entry__2"><code class="ph codeph">dita</code></td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="markdown-dita-syntax-reference__links__entry__1"><code class="ph codeph">.xml</code></td>
<td class="entry colsep-0 rowsep-1" headers="markdown-dita-syntax-reference__links__entry__2"><code class="ph codeph">dita</code></td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="markdown-dita-syntax-reference__links__entry__1"><code class="ph codeph">.md</code></td>
<td class="entry colsep-0 rowsep-1" headers="markdown-dita-syntax-reference__links__entry__2"><code class="ph codeph">markdown</code></td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="markdown-dita-syntax-reference__links__entry__1"><code class="ph codeph">.markdown</code></td>
<td class="entry colsep-0 rowsep-1" headers="markdown-dita-syntax-reference__links__entry__2"><code class="ph codeph">markdown</code></td>
</tr>
</tbody></table>
<p class="p">All other link targets use <code class="ph codeph">format</code> from file extension and are treated as non-DITA files.
Absolute links targets are treated as external scope links:</p>
<pre class="pre codeblock language-markdown normalize-space show-line-numbers show-whitespace"><code>[Markdown](test.md)
[DITA](test.dita)
[HTML](test.html)
[External](http://www.example.com/test.html)</code></pre>
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;xref href="test.md"&gt;Markdown&lt;/xref&gt;
&lt;xref href="test.dita"&gt;DITA&lt;/xref&gt;
&lt;xref href="test.html" format="html"&gt;HTML&lt;/xref&gt;
&lt;xref href="http://www.example.com/test.html" format="html" scope="external"&gt;External&lt;/xref&gt;</code></pre>
</section>
<section class="section" id="markdown-dita-syntax-reference__images"><h2 class="title sectiontitle">Images</h2>
<p class="p">Images used in inline content will result in inline placement. If a block level image contains a title, it will
be treated as an image wrapped in figure:</p>
<pre class="pre codeblock language-markdown normalize-space show-line-numbers show-whitespace"><code>An inline ![Alt](test.jpg).
![Alt](test.jpg)
![Alt](test.jpg "Title")</code></pre>
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;p&gt;An inline &lt;image href="test.jpg"&gt;&lt;alt&gt;Alt&lt;/alt&gt;&lt;/image&gt;.&lt;/p&gt;
&lt;image href="test.jpg" placement="break"&gt;
&lt;alt&gt;Alt&lt;/alt&gt;
&lt;/image&gt;
&lt;fig&gt;
&lt;title&gt;Title&lt;/title&gt;
&lt;image href="test.jpg"&gt;
&lt;alt&gt;Alt&lt;/alt&gt;
&lt;/image&gt;
&lt;/fig&gt;</code></pre>
</section>
<section class="section" id="markdown-dita-syntax-reference__key-references"><h2 class="title sectiontitle">Key references</h2>
<p class="p">Key reference can be used with
<a class="xref" href="http://spec.commonmark.org/0.18/#shortcut-reference-link" target="_blank" rel="external noopener">shortcut
reference links</a>:</p>
<pre class="pre codeblock language-markdown normalize-space show-line-numbers show-whitespace"><code>[key]
![image-key]</code></pre>
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;xref keyref="key"/&gt;
&lt;image keyref="image-key"/&gt;</code></pre>
</section>
<section class="section" id="markdown-dita-syntax-reference__inline"><h2 class="title sectiontitle">Inline</h2>
<p class="p">The following inline elements are supported:</p>
<pre class="pre codeblock language-markdown normalize-space show-line-numbers show-whitespace"><code>**bold**
*italic*
`code`
~~strikethrough~~</code></pre>
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;b&gt;bold&lt;/b&gt;
&lt;i&gt;italic&lt;/i&gt;
&lt;codeph&gt;code&lt;/codeph&gt;
&lt;ph status="deleted"&gt;strikethrough&lt;/ph&gt;</code></pre>
</section>
<section class="section" id="markdown-dita-syntax-reference__lists"><h2 class="title sectiontitle">Lists</h2>
<p class="p">Unordered can be marked up with either hyphen or asterisk:</p>
<pre class="pre codeblock language-markdown normalize-space show-line-numbers show-whitespace"><code>* one
* two
- three
- four</code></pre>
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;ul&gt;
&lt;li&gt;one&lt;/li&gt;
&lt;li&gt;two
&lt;ul&gt;
&lt;li&gt;three&lt;/li&gt;
&lt;li&gt;four&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;/ul&gt;</code></pre>
<p class="p">Ordered can be marked up with either number or number sign, followed by a period:</p>
<pre class="pre codeblock language-markdown normalize-space show-line-numbers show-whitespace"><code>1. one
2. two
#. three
#. four</code></pre>
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;ol&gt;
&lt;li&gt;one&lt;/li&gt;
&lt;li&gt;two
&lt;ol&gt;
&lt;li&gt;three&lt;/li&gt;
&lt;li&gt;four&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;/ul&gt;</code></pre>
<p class="p">Definition lists use the
<a class="xref" href="http://michelf.com/projects/php-markdown/extra/#def-list" target="_blank" rel="external noopener">PHP
Markdown Extra</a> format:</p>
<pre class="pre codeblock language-markdown normalize-space show-line-numbers show-whitespace"><code>Term
: Definition.</code></pre>
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;dl&gt;
&lt;delentry&gt;
&lt;dt&gt;Term&lt;/dt&gt;
&lt;dd&gt;Defintion.&lt;/dd&gt;
&lt;/delentry&gt;
&lt;/dl&gt;</code></pre>
<p class="p">Each definition entry must have only one term and contain only inline content.</p></section>
<section class="section" id="markdown-dita-syntax-reference__tables"><h2 class="title sectiontitle">Tables</h2>
<p class="p">Tables use
<a class="xref" href="http://fletcherpenney.net/multimarkdown/" target="_blank" rel="external noopener">MultiMarkdown</a> table
extension format:</p>
<pre class="pre codeblock normalize-space show-line-numbers show-whitespace"><code>| First Header | Second Header | Third Header |
| ------------ | :-----------: | -----------: |
| Content | *Long Cell* ||
| Content | **Cell** | Cell |</code></pre>
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;table&gt;
&lt;tgroup cols="3"&gt;
&lt;colspec colname="col1"/&gt;
&lt;colspec colname="col2" align="center"/&gt;
&lt;colspec colname="col3" align="right"/&gt;
&lt;thead&gt;
&lt;row&gt;
&lt;entry&gt;First Header &lt;/entry&gt;
&lt;entry&gt;Second Header &lt;/entry&gt;
&lt;entry&gt;Third Header &lt;/entry&gt;
&lt;/row&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;row&gt;
&lt;entry&gt;Content &lt;/entry&gt;
&lt;entry namest="col2" nameend="col3"&gt;&lt;i&gt;Long Cell&lt;/i&gt;&lt;/entry&gt;
&lt;/row&gt;
&lt;row&gt;
&lt;entry&gt;Content &lt;/entry&gt;
&lt;entry&gt;&lt;b&gt;Cell&lt;/b&gt;&lt;/entry&gt;
&lt;entry&gt;Cell &lt;/entry&gt;
&lt;/row&gt;
&lt;/tbody&gt;
&lt;/tgroup&gt;
&lt;/table&gt;</code></pre>
<p class="p">Table cells may only contain inline content and column spans; block content and row spans are not supported by
Markdown DITA.</p></section>
<section class="section" id="markdown-dita-syntax-reference__metadata"><h2 class="title sectiontitle">Metadata</h2>
<p class="p">
<a class="xref" href="http://www.yaml.org/" target="_blank" rel="external noopener">YAML</a> metadata block as defined in Pandoc
<a class="xref" href="http://pandoc.org/MANUAL.html#extension-yaml_metadata_block" target="_blank" rel="external noopener">pandoc_metadata_block</a> can be used to specify different metadata elements. The supported elements
are:</p>
<ul class="ul">
<li class="li">
<code class="ph codeph">author</code></li>
<li class="li">
<code class="ph codeph">source</code></li>
<li class="li">
<code class="ph codeph">publisher</code></li>
<li class="li">
<code class="ph codeph">permissions</code></li>
<li class="li">
<code class="ph codeph">audience</code></li>
<li class="li">
<code class="ph codeph">category</code></li>
<li class="li">
<code class="ph codeph">keyword</code></li>
<li class="li">
<code class="ph codeph">resourceid</code></li>
</ul>
<p class="p">Unrecognized keys are output using <code class="ph codeph">data</code> element.</p>
<pre class="pre codeblock language-markdown normalize-space show-line-numbers show-whitespace"><code>---
author:
- Author One
- Author Two
source: Source
publisher: Publisher
permissions: Permissions
audience: Audience
category: Category
keyword:
- Keyword1
- Keyword2
resourceid:
- Resourceid1
- Resourceid2
workflow: review
---
# Sample with YAML header</code></pre>
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;title&gt;Sample with YAML header&lt;/title&gt;
&lt;prolog&gt;
&lt;author&gt;Author One&lt;/author&gt;
&lt;author&gt;Author Two&lt;/author&gt;
&lt;source&gt;Source&lt;/source&gt;
&lt;publisher&gt;Publisher&lt;/publisher&gt;
&lt;permissions view="Permissions"/&gt;
&lt;metadata&gt;
&lt;audience audience="Audience"/&gt;
&lt;category&gt;Category&lt;/category&gt;
&lt;keywords&gt;
&lt;keyword&gt;Keyword1&lt;/keyword&gt;
&lt;keyword&gt;Keyword2&lt;/keyword&gt;
&lt;/keywords&gt;
&lt;/metadata&gt;
&lt;resourceid appid="Resourceid1"/&gt;
&lt;resourceid appid="Resourceid2"/&gt;
&lt;data name="workflow" value="review"/&gt;
&lt;/prolog&gt;</code></pre>
</section>
</div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/input-formats.html" title="In addition to standard DITA XML, DITA-OT supports several alternative input formats, including Markdown and the proposed XDITA, MDITA and HDITA authoring formats currently in development for Lightweight DITA.">Authoring formats</a></div></div><div class="linklist relinfo"><strong>Related information</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/dita-xml-input.html" title="DITA Open Toolkit supports all released versions of the OASIS DITA specification, including 1.0, 1.1, 1.2, and 1.3. As of release 3.6, DITA-OT also provides an initial preview of features for the latest draft of the upcoming DITA 2.0 standard.">Standard DITA XML</a></li><li class="linklist"><a class="link" href="../topics/markdown-input.html" title="Markdown is a lightweight markup language that allows you to write using an easy-to-read plain text format and convert to structurally valid markup as necessary.">Markdown content</a></li><li class="linklist"><a class="link" href="../topics/lwdita-input.html" title="DITA-OT provides preview support for the authoring formats proposed for Lightweight DITA, or “LwDITA”. The XDITA, MDITA and HDITA formats are alternative representations of DITA content in XML, Markdown and HTML5.">Preview support for Lightweight DITA</a></li></ul></div></nav></article></main></body></html>

60
dita-ot-3.6/doc/topics/markdown-input.html Normal file
View file

@ -0,0 +1,60 @@
<!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="Markdown is a lightweight markup language that allows you to write using an easy-to-read plain text format and convert to structurally valid markup as necessary."><meta name="keywords" content=", format, authoring formats, Markdown, CommonMark, converting lightweight formats to DITA"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Markdown content</title></head><body id="markdown-input"><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><ul><li><a href="../topics/dita-xml-input.html">Standard DITA XML</a></li><li class="active"><a href="../topics/markdown-input.html">Markdown content</a></li><li><a href="../topics/lwdita-input.html">Lightweight DITA</a></li><li><a href="../topics/markdown-dita-syntax-reference.html">Markdown DITA syntax</a></li></ul></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></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">Markdown content</h1>
<div class="body"><p class="shortdesc">
<a class="xref" href="https://daringfireball.net/projects/markdown/" target="_blank" rel="external noopener">Markdown</a> is a lightweight markup language that allows you to write using an easy-to-read plain text
format and convert to structurally valid markup as necessary.</p>
<p class="p">In the words of its creators:</p>
<blockquote class="lq">“The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is
that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been
marked up with tags or formatting instructions.”</blockquote>
<p class="p">DITA Open Toolkit now allows you to use Markdown files directly in topic references and export DITA content as
Markdown.</p>
<p class="p">These features enable lightweight authoring scenarios that allow subject matter experts to contribute to DITA
publications without writing in XML, and support publishing workflows that include DITA content in Markdown-based
publishing systems.</p>
<section class="section"><h2 class="title sectiontitle">Adding Markdown topics</h2>
<p class="p">To add a Markdown topic to a DITA publication, create a topic reference in your map and set the
<code class="keyword markupname xmlatt">@format</code> attribute to <code class="ph codeph">markdown</code> so the toolkit will recognize the source file
as Markdown and convert it to DITA:</p>
<div class="p"><pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd"&gt;
&lt;map&gt;
&lt;topicref href="markdown-dita-topic.md" <strong class="ph b">format="markdown"</strong>/&gt;
&lt;/map&gt;</code></pre></div>
<p class="p">The <code class="ph codeph">markdown</code> format uses a relatively lenient document parsing approach to support a wide
range of content and Markdown syntax constructs.</p>
<div class="note note note_note"><span class="note__title">Note:</span> The Markdown support is based on
<a class="xref" href="http://commonmark.org" target="_blank" rel="external noopener">CommonMark</a>, a strongly defined, highly compatible specification of Markdown.</div>
<p class="p">When you add Markdown topics to a DITA publication as described above, the content is temporarily converted to
DITA in the background when generating other output formats like HTML or PDF, but the Markdown source files
remain unchanged.</p>
<div class="note tip note_tip"><span class="note__title">Tip:</span> This approach is recommended in cases where simple content is authored collaboratively over
multiple versions, as Markdown topics can be edited by a wide range of authors and combined as necessary with
more complex content maintained in DITA XML.</div>
</section>
<section class="section"><h2 class="title sectiontitle">Converting Markdown to DITA</h2>
<p class="p">In cases where the Markdown input is a one-off contribution, members of the DITA authoring team can use the
Markdown file as raw material that is easily converted to DITA and enriched with conditional processing
attributes, conkeyrefs or other more complex semantics that have no equivalent in limited formats like
Markdown.</p>
<p class="p">If you prefer to maintain this content in DITA in the future, you can generate DITA output by passing the
<span class="keyword parmname">--format</span>=<span class="keyword option">dita</span> option on the command line.</p>
<p class="p">This converts all input files (both DITA XML and Markdown) to
<a class="xref" href="dita2dita.html" title="The dita transformation generates normalized topics and maps from DITA input. The normalized output includes the results of DITA Open Toolkit pre-processing operations, which resolve map references, keys, content references, code references and push metadata back and forth between maps and topics.">Normalized DITA</a>. You can then copy the generated DITA files from the output
folder to your project and replace references to the Markdown topics with their DITA equivalents.</p>
</section>
</div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/input-formats.html" title="In addition to standard DITA XML, DITA-OT supports several alternative input formats, including Markdown and the proposed XDITA, MDITA and HDITA authoring formats currently in development for Lightweight DITA.">Authoring formats</a></div></div><div class="linklist relinfo"><strong>Related information</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/dita-xml-input.html" title="DITA Open Toolkit supports all released versions of the OASIS DITA specification, including 1.0, 1.1, 1.2, and 1.3. As of release 3.6, DITA-OT also provides an initial preview of features for the latest draft of the upcoming DITA 2.0 standard.">Standard DITA XML</a></li><li class="linklist"><a class="link" href="../topics/lwdita-input.html" title="DITA-OT provides preview support for the authoring formats proposed for Lightweight DITA, or “LwDITA”. The XDITA, MDITA and HDITA formats are alternative representations of DITA content in XML, Markdown and HTML5.">Preview support for Lightweight DITA</a></li><li class="linklist"><a class="link" href="../topics/markdown-dita-syntax-reference.html" title="Markdown DITA uses CommonMark as the underlying markup language.">Markdown DITA syntax reference</a></li><li class="linklist"><a class="link" href="https://www.oxygenxml.com/events/2015/dita-ot_day.html#Markdown_plugin" target="_blank" rel="external noopener" title="This talk introduces Jarno Elovirta’s DITA-OT Markdown plugins, which extend the DITA Open Toolkit so you can use Markdown files directly in topic references and export existing DITA content in Markdown format for use in other publishing systems. This makes it easier for people to contribute content to DITA publications, enables mobile authoring workflows, facilitates review processes with less technical audiences and expands the range of publishing options to workflows based on Markdown.">Markdown plugin</a></li></ul></div></nav></article></main></body></html>

153
dita-ot-3.6/doc/topics/migrating-ant-to-dita.html Normal file
View file

@ -0,0 +1,153 @@
<!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="Although DITA Open Toolkit still supports Ant builds, switching to the dita command offers a simpler command interface, sets all required environment variables and allows you to run DITA-OT without setting up anything beforehand."><meta name="keywords" content="Ant, exec, dita-cmd, command, benefits of, dita, command, migrating Ant scripts, classpath, command"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Migrating Ant builds to use the dita command</title></head><body id="migrating-ant-to-dita"><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><ul><li><a href="../topics/build-using-dita-command.html">Using the dita command</a><ul><li><a href="../topics/using-dita-properties-file.html">Using a properties file</a></li><li class="active"><a href="../topics/migrating-ant-to-dita.html">Migrating Ant builds</a></li><li><a href="../topics/using-project-files.html">Using a project file</a></li></ul></li><li><a href="../topics/using-docker-images.html">Using Docker images</a></li><li><a href="../topics/publishing-with-ant.html">Using Ant</a></li><li><a href="../reference/java-api.html">Using the Java API</a></li></ul></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></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 Ant builds to use the <span class="keyword cmdname">dita</span> command</h1>
<div class="body taskbody"><p class="shortdesc">Although DITA Open Toolkit still supports Ant builds, switching to the <span class="keyword cmdname">dita</span> command
offers a simpler command interface, sets all required environment variables and allows you to run DITA-OT without
setting up anything beforehand.</p>
<section class="section context"><div class="tasklabel"><h2 class="sectiontitle tasklabel">About this task</h2></div>
<p class="p">Building output with the <span class="keyword cmdname">dita</span> command is often easier than using Ant. In particular, you can
use <span class="ph filepath">.properties</span> files to specify sets of DITA-OT parameters for each build.</p>
<p class="p">You can include the <span class="keyword cmdname">dita</span> command in shell scripts to perform multiple builds.</p>
<div class="note tip note_tip"><span class="note__title">Tip:</span> Add the absolute path for the <span class="ph filepath">bin</span> folder of the DITA-OT installation
directory to the
<a class="xref" href="https://en.wikipedia.org/wiki/PATH_(variable)" target="_blank" rel="external noopener">PATH environment variable</a> to run the <span class="keyword cmdname">dita</span> command from any location on the file system without
typing the path.</div>
</section>
<section><div class="tasklabel"><h2 class="sectiontitle tasklabel">Procedure</h2></div><ol class="ol steps"><li class="li step stepexpand">
<span class="ph cmd">In your Ant build file, identify the properties set in each build target.</span>
<div class="itemgroup info">
<div class="note note note_note"><span class="note__title">Note:</span> Some build parameters might be specified as properties of the project as a whole. You can refer to a
build log to see a list of all properties that were set for the build.</div>
</div>
</li><li class="li step stepexpand">
<span class="ph cmd">Create a <span class="ph filepath">.properties</span> file for each build and specify the needed build parameters, one
per line, in the format <code class="ph codeph">name = value</code>.</span>
</li><li class="li step stepexpand">
<span class="ph cmd">Use the <span class="keyword cmdname">dita</span> command to perform each build, referencing your
<span class="ph filepath">.properties</span> with the <span class="keyword parmname">--propertyfile</span>=<var class="keyword varname">file</var>
option.</span>
</li></ol></section>
<section class="example"><h2 class="title sectiontitle">Example: Ant build</h2>
<p class="p">Prior to DITA-OT 2.0, an Ant build like this was typically used to define the properties for each target.</p>
<div class="p">Sample build file: <span class="ph filepath" id="migrating-ant-to-dita__samples-dir"><var class="keyword varname">dita-ot-dir</var>/docsrc/samples</span><span class="ph filepath">/ant_sample/build-chm-pdf.xml</span>
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;project name="build-chm-pdf" default="all" basedir="."&gt;
&lt;property name="dita.dir" location="${basedir}/../../.."/&gt;
&lt;target name="all" description="build CHM and PDF" depends="chm,pdf"/&gt;
&lt;target name="chm" description="build CHM"&gt;
&lt;ant antfile="${dita.dir}/build.xml"&gt;
&lt;property name="args.input" location="../sequence.ditamap"/&gt;
&lt;property name="transtype" value="htmlhelp"/&gt;
&lt;property name="output.dir" location="../out/chm"/&gt;
&lt;property name="args.gen.task.lbl" value="YES"/&gt;
&lt;/ant&gt;
&lt;/target&gt;
&lt;target name="pdf" description="build PDF"&gt;
&lt;ant antfile="${dita.dir}/build.xml"&gt;
&lt;property name="args.input" location="../taskbook.ditamap"/&gt;
&lt;property name="transtype" value="pdf"/&gt;
&lt;property name="output.dir" location="../out/pdf"/&gt;
&lt;property name="args.gen.task.lbl" value="YES"/&gt;
&lt;property name="args.rellinks" value="nofamily"/&gt;
&lt;/ant&gt;
&lt;/target&gt;
&lt;/project&gt;</code></pre></div></section>
<section class="example"><h2 class="title sectiontitle">Example: <span class="ph filepath">.properties</span> files with <span class="keyword cmdname">dita</span> command</h2>
<p class="p">The following <span class="ph filepath">.properties</span> files and <span class="keyword cmdname">dita</span> commands are equivalent to the
example Ant build.</p>
<p class="p">Sample <span class="ph filepath">.properties</span> file: <span class="ph filepath"><var class="keyword varname">dita-ot-dir</var>/docsrc/samples</span><span class="ph filepath">/properties/chm.properties</span></p>
<div class="p">
<pre class="pre codeblock language-properties normalize-space show-line-numbers show-whitespace"><code>output.dir = out/chm
args.gen.task.lbl = YES</code></pre></div>
<p class="p">Sample <span class="ph filepath">.properties</span> file: <span class="ph filepath"><var class="keyword varname">dita-ot-dir</var>/docsrc/samples</span><span class="ph filepath">/properties/pdf.properties</span></p>
<div class="p">
<pre class="pre codeblock language-properties normalize-space show-line-numbers show-whitespace"><code>output.dir = out/pdf
args.gen.task.lbl = YES
args.rellinks = nofamily</code></pre></div>
<p class="p">Run from <span class="ph filepath"><var class="keyword varname">dita-ot-dir</var>/docsrc/samples</span>:</p>
<pre class="pre codeblock"><code><span class="keyword cmdname">dita</span> <span class="keyword parmname">--input</span>=<span class="ph filepath">sequence.ditamap</span> <span class="keyword parmname">--format</span>=<span class="keyword option">htmlhelp</span> \
<span class="keyword parmname">--propertyfile</span>=<span class="ph filepath">properties/chm.properties</span>
<span class="keyword cmdname">dita</span> <span class="keyword parmname">--input</span>=<span class="ph filepath">taskbook.ditamap</span> <span class="keyword parmname">--format</span>=<span class="keyword option">pdf</span> \
<span class="keyword parmname">--propertyfile</span>=<span class="ph filepath">properties/pdf.properties</span></code></pre>
</section>
<section class="example"><h2 class="title sectiontitle">Example: Call the <span class="keyword cmdname">dita</span> command from an Ant build</h2>
<p class="p">In some cases, you might still want to use an Ant build to implement some pre- or post-processing steps, but
also want the convenience of using the <span class="keyword cmdname">dita</span> command with <span class="ph filepath">.properties</span>
files to define the parameters for each build. This can be accomplished with Ant’s <code class="keyword markupname xmlelement">&lt;exec&gt;</code>
task.</p>
<p class="p">This example uses a <code class="keyword markupname xmlelement">&lt;dita-cmd&gt;</code> Ant macro defined in the <span class="ph filepath"><var class="keyword varname">dita-ot-dir</var>/docsrc/samples</span><span class="ph filepath">/ant_sample/dita-cmd.xml</span> file:</p>
<div class="p">
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;macrodef name="dita-cmd"&gt;
&lt;attribute name="input"/&gt;
&lt;attribute name="format"/&gt;
&lt;attribute name="propertyfile"/&gt;
&lt;sequential&gt;
&lt;!-- For Unix run the DITA executable--&gt;
&lt;exec taskname="dita-cmd" executable="${dita.dir}/bin/dita" osfamily="unix" failonerror="true"&gt;
&lt;arg value="--input"/&gt;
&lt;arg value="@{input}"/&gt;
&lt;arg value="--format"/&gt;
&lt;arg value="@{format}"/&gt;
&lt;arg value="--propertyfile"/&gt;
&lt;arg value="@{propertyfile}"/&gt;
&lt;/exec&gt;
&lt;!-- For Windows run DITA from a DOS command --&gt;
&lt;exec taskname="dita-cmd" dir="${dita.dir}/bin" executable="cmd" osfamily="windows" failonerror="true"&gt;
&lt;arg value="/C"/&gt;
&lt;arg value="dita --input @{input} --format @{format} --propertyfile=@{propertyfile}"/&gt;
&lt;/exec&gt;
&lt;/sequential&gt;
&lt;/macrodef&gt;</code></pre></div>
<div class="p">You can use this macro in your Ant build to call the <span class="keyword cmdname">dita</span> command and pass the
<span class="keyword parmname">input</span>, <span class="keyword parmname">format</span> and <span class="keyword parmname">propertyfile</span> parameters as
follows:
<pre class="pre codeblock language-xml"><code>&lt;dita-cmd input="sample.ditamap" format="pdf" propertyfile="sample.properties"/&gt;</code></pre>
</div>
<p class="p">This approach allows you to use Ant builds to perform additional tasks at build time while allowing the
<span class="keyword cmdname">dita</span> command to set the classpath and ensure that all necessary JAR libraries are
available.</p>
<div class="note note note_note"><span class="note__title">Note:</span> The attributes defined in the Ant macro are required and must be supplied each time the task is run. To set
optional parameters in one build (but not another), use different <span class="ph filepath">.properties</span> files for
each build.</div>
<p class="p">Sample build file: <span class="ph filepath"><var class="keyword varname">dita-ot-dir</var>/docsrc/samples</span><span class="ph filepath">/ant_sample/build-chm-pdf-hybrid.xml</span></p>
<div class="p">
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;project name="build-chm-pdf-hybrid" default="all" basedir="."&gt;
&lt;description&gt;An Ant build that calls the dita command&lt;/description&gt;
&lt;include file="dita-cmd.xml"/&gt;&lt;!-- defines the &lt;dita-cmd&gt; macro --&gt;
&lt;target name="all" depends="pre,main,post"/&gt;
&lt;target name="pre"&gt;
&lt;description&gt;Preprocessing steps&lt;/description&gt;
&lt;/target&gt;
&lt;target name="main"&gt;
&lt;description&gt;Build the CHM and PDF with the dita command&lt;/description&gt;
&lt;property name="absolute.path.base" location="../"/&gt;
&lt;dita-cmd
input="${absolute.path.base}/sequence.ditamap"
format="htmlhelp"
propertyfile="${absolute.path.base}/properties/chm.properties"
/&gt;
&lt;dita-cmd
input="${absolute.path.base}/taskbook.ditamap"
format="pdf"
propertyfile="${absolute.path.base}/properties/pdf.properties"
/&gt;
&lt;/target&gt;
&lt;target name="post"&gt;
&lt;description&gt;Postprocessing steps&lt;/description&gt;
&lt;/target&gt;
&lt;/project&gt;</code></pre>
</div>
</section>
</div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/build-using-dita-command.html" title="You can generate output using the dita command-line tool. Build parameters can be specified on the command line or with .properties files.">Building output using the dita command</a></div></div></nav></article></main></body></html>

149
dita-ot-3.6/doc/topics/migrating-to-1.5.4.html Normal file
View file

@ -0,0 +1,149 @@
<!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 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."><meta name="keywords" content="deprecated features, print_transtypes, page-margin-left, page-margin-right, languages, supported, Finnish, Hebrew, Indonesian, Kazakh, Malay, Romanian, Russian, Swedish, I18N, org.dita.pdf2.i18n.enabled"><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 1.5.4</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><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 class="active"><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 1.5.4</h1>
<div class="body refbody"><p class="shortdesc">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.</p>
<section class="section" id="ID__section_vc5_gld_g2"><h2 class="title sectiontitle">Configuration properties file changes</h2>
<p class="p">In previous versions, the <span class="ph filepath">lib/configuration.properties</span> file was generated by the
integration process. Integration has been changed to generate
<span class="ph filepath">lib/org.dita.dost.platform/plugin.properties</span> and the role of the old
<span class="ph filepath">lib/configuration.properties</span> has been changed to contain defaults and configuration
options, such as default language.</p>
<p class="p">The <code class="ph codeph">dita.plugin.org.dita.*.dir</code> properties have been changed to point to the DITA-OT base
directory.</p>
<p class="p">To allow access to configuration files, the <span class="ph filepath">lib</span> directory needs to be added to the Java
classpath.</p>
</section>
<section class="section"><h2 class="title sectiontitle">New plug-in extension points </h2>
<p class="p">New plug-in extension points have been added allow configuring DITA-OT behavior based on file extensions.</p>
<table class="table table-hover frame-none"><caption></caption><colgroup><col style="width:33.33333333333333%"><col style="width:33.33333333333333%"><col style="width:33.33333333333333%"></colgroup><thead class="thead">
<tr class="row">
<th class="entry colsep-0 rowsep-1" id="ID__entry__1">Extension point</th>
<th class="entry colsep-0 rowsep-1" id="ID__entry__2">Description</th>
<th class="entry colsep-0 rowsep-1" id="ID__entry__3">Default values</th>
</tr>
</thead><tbody class="tbody">
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="ID__entry__1"><span class="keyword parmname">dita.topic.extension</span></td>
<td class="entry colsep-0 rowsep-1" headers="ID__entry__2">DITA topic</td>
<td class="entry colsep-0 rowsep-1" headers="ID__entry__3"><span class="ph filepath">.dita</span>, <span class="ph filepath">.xml</span></td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="ID__entry__1"><span class="keyword parmname">dita.map.extensions</span></td>
<td class="entry colsep-0 rowsep-1" headers="ID__entry__2">DITA map</td>
<td class="entry colsep-0 rowsep-1" headers="ID__entry__3"><span class="ph filepath">.ditamap</span></td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="ID__entry__1"><span class="keyword parmname">dita.html.extensions</span></td>
<td class="entry colsep-0 rowsep-1" headers="ID__entry__2">HTML file</td>
<td class="entry colsep-0 rowsep-1" headers="ID__entry__3"><span class="ph filepath">.html</span>, <span class="ph filepath">.htm</span></td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="ID__entry__1"><span class="keyword parmname">dita.resource.extensions</span></td>
<td class="entry colsep-0 rowsep-1" headers="ID__entry__2">Resource file</td>
<td class="entry colsep-0 rowsep-1" headers="ID__entry__3"><span class="ph filepath">.pdf</span>, <span class="ph filepath">.swf</span></td>
</tr>
</tbody></table>
<p class="p">Both HTML and resource file extensions are used to determine if a file in source is copied to output.</p>
<p class="p">A new plug-in extension point has been added to declare transformation types as print types.</p>
<table class="table table-hover frame-none"><caption></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="ID__entry__16">Extension point</th>
<th class="entry colsep-0 rowsep-1" id="ID__entry__17">Description</th>
</tr>
</thead><tbody class="tbody">
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="ID__entry__16"><span class="keyword parmname">dita.transtype.print</span></td>
<td class="entry colsep-0 rowsep-1" headers="ID__entry__17">Declare transformation type as a print type.</td>
</tr>
</tbody></table>
<p class="p">The <code class="ph codeph">print_transtypes</code> property in <span class="ph filepath">integrator.properties</span> has been
deprecated in favor of <span class="keyword parmname">dita.transtype.print</span>.</p>
</section>
<section class="section"><h2 class="title sectiontitle">Plugin URI scheme</h2>
<p class="p">Support for the <span class="keyword">plugin</span> URI scheme has been added to XSLT stylesheets. Plug-ins can refer to
files in other plug-ins without hard-coding relative paths, for example: </p>
<pre class="pre codeblock language-xml"><code>&lt;xsl:import href="plugin:org.dita.pdf2:xsl/fo/topic2fo_1.0.xsl"/&gt;</code></pre>
</section>
<section class="section"><h2 class="title sectiontitle">XHTML</h2>
<p class="p">Support for the following languages has been added:</p>
<ul class="ul">
<li class="li">Indonesian</li>
<li class="li">Kazakh</li>
<li class="li">Malay</li>
</ul>
</section>
<section class="section"><h2 class="title sectiontitle">PDF</h2>
<p class="p">Support for mirrored page layout was added. The default is the unmirrored layout. The following XSLT
configuration variables have been deprecated:</p>
<ul class="ul" id="ID__ul_hkv_oyj_bd">
<li class="li"><code class="ph codeph">page-margin-left</code></li>
<li class="li"><code class="ph codeph">page-margin-right</code></li>
</ul>
<p class="p">The following variables should be used instead to control page margins:</p>
<ul class="ul" id="ID__ul_yda_wyj_bd">
<li class="li"><code class="ph codeph">page-margin-outside</code></li>
<li class="li"><code class="ph codeph">page-margin-inside</code></li>
</ul>
<p class="p">The <span class="keyword parmname">args.bookmap-order</span> property has been added to control how front and back matter are
processed in bookmaps. The default is to reorder the frontmatter content as in previous releases.</p>
<p class="p">A new extension point has been added to add mappings to the PDF configuration catalog file.</p>
<table class="table table-hover frame-none"><caption></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="ID__entry__20">Extension point</th>
<th class="entry colsep-0 rowsep-1" id="ID__entry__21">Description</th>
</tr>
</thead><tbody class="tbody">
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="ID__entry__20"><span class="keyword parmname">org.dita.pdf2.catalog.relative</span></td>
<td class="entry colsep-0 rowsep-1" headers="ID__entry__21">Configuration catalog includes.</td>
</tr>
</tbody></table>
<p class="p">Support for the following languages has been added:</p>
<ul class="ul">
<li class="li">Finnish</li>
<li class="li">Hebrew</li>
<li class="li">Romanian</li>
<li class="li">Russian</li>
<li class="li">Swedish</li>
</ul>
<p class="p">PDF processing no longer copies images or generates XSL FO to output directory. Instead, the temporary
directory is used for all temporary files and source images are read directly from source directory. The legacy
processing model can be enabled by setting <span class="keyword parmname">org.dita.pdf2.use-out-temp</span> to
<span class="keyword option">true</span> in configuration properties; support for the legacy processing model may be removed in
future releases.</p>
<p class="p">Support for FrameMaker index syntax has been disabled by default. To enable FrameMaker index syntax, set
<span class="keyword parmname">org.dita.pdf2.index.frame-markup</span> to <span class="keyword option">true</span> in configuration
properties.</p>
<p class="p">A configuration option has been added to disable internationalization (I18N) font processing and use
stylesheet-defined fonts. To disable I18N font processing, set <span class="keyword parmname">org.dita.pdf2.i18n.enabled</span>
to <code class="ph codeph">false</code> in configuration properties.</p>
<p class="p">The XSLT parameters <span class="keyword parmname">customizationDir</span> and <span class="keyword parmname">fileProfilePrefix</span> have been
removed in favor of the <span class="keyword parmname">customizationDir.url</span> parameter.</p>
<p class="p">A new shell stylesheet has been added for FOP and other shell stylesheets have also been revised. Plug-ins
which have their own shell stylesheets for PDF processing should make sure all required stylesheets are
imported.</p>
<p class="p">Font family definitions in stylesheets have been changed from Sans, Serif, and Monospaced to sans-serif, serif,
and monospace, respectively. The I18N font processing still uses the old logical names and aliases are used to
map the new names to old ones. </p>
</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>

174
dita-ot-3.6/doc/topics/migrating-to-1.6.html Normal file
View file

@ -0,0 +1,174 @@
<!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="In DITA-OT 1.6, various demo 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 &#34;bkinfo&#34; demo plug-in, or layout-masters.xml configuration."><meta name="keywords" content="deprecated features, folder, demo, processing instruction, workdir, topic pull templates, list of, &#34;bkinfo&#34; demo plug-in, layout-masters.xml, PDF2 templates, list of, XHTML templates, list of, ODT templates, list of"><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 1.6</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><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 class="active"><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 1.6</h1>
<div class="body refbody"><p class="shortdesc">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.</p>
<section class="section">
<p class="p">Support for the old DITAVAL format (used before OASIS added DITAVAL to the standard in 2007) has been
removed.</p>
<p class="p">The <span class="ph filepath">demo</span> folder has been deprecated and the following plug-ins have been moved to the
<span class="ph filepath">plugins</span> folder:</p>
<table class="table table-hover frame-none"><caption></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="ID__entry__1">old path</th>
<th class="entry colsep-0 rowsep-1" id="ID__entry__2">new path</th>
</tr>
</thead><tbody class="tbody">
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="ID__entry__1"><span class="ph filepath">demo/dita11</span></td>
<td class="entry colsep-0 rowsep-1" headers="ID__entry__2"><span class="ph filepath">plugins/org.dita.specialization.dita11</span></td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="ID__entry__1"><span class="ph filepath">demo/dita132</span></td>
<td class="entry colsep-0 rowsep-1" headers="ID__entry__2"><span class="ph filepath">plugins/org.dita.specialization.dita132</span></td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="ID__entry__1"><span class="ph filepath">demo/eclipsemap</span></td>
<td class="entry colsep-0 rowsep-1" headers="ID__entry__2"><span class="ph filepath">plugins/org.dita.specialization.eclipsemap</span></td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="ID__entry__1"><span class="ph filepath">demo/fo</span></td>
<td class="entry colsep-0 rowsep-1" headers="ID__entry__2"><span class="ph filepath">plugins/org.dita.pdf2</span></td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="ID__entry__1"><span class="ph filepath">demo/tocjs</span></td>
<td class="entry colsep-0 rowsep-1" headers="ID__entry__2"><span class="ph filepath">plugins/com.sophos.tocjs</span></td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="ID__entry__1"><span class="ph filepath">demo/h2d</span></td>
<td class="entry colsep-0 rowsep-1" headers="ID__entry__2"><span class="ph filepath">plugins/h2d</span></td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="ID__entry__1"><span class="ph filepath">demo/legacypdf</span></td>
<td class="entry colsep-0 rowsep-1" headers="ID__entry__2"><span class="ph filepath">plugins/legacypdf</span></td>
</tr>
</tbody></table>
<p class="p">The remaining plug-ins in the demo folder have been moved to a separate repository at
<a class="xref" href="https://github.com/dita-ot/ext-plugins" target="_blank" rel="external noopener">github.com/dita-ot/ext-plugins</a>.</p>
</section>
<section class="section">
<p class="p">The deprecated property <code class="ph codeph">dita.input.valfile</code> should be replaced with the new argument property
<code class="ph codeph">args.filter</code>.</p>
<p class="p">The <code class="ph codeph">dita-preprocess</code> target has been removed and dependencies should be replaced with a target
sequence <code class="ph codeph">build-init, preprocess</code>.</p>
<p class="p">Support for the <code class="ph codeph">args.message.file</code> argument has been removed as message configuration has
become static configuration.</p>
<p class="p">The <code class="ph codeph">workdir</code> processing instruction has been deprecated in favor of
<code class="ph codeph">workdir-uri</code>. The only difference between the two processing instructions is that
<code class="ph codeph">workdir-uri</code> contains a URI instead of a system path.</p>
</section>
<section class="section"><h2 class="title sectiontitle">Preprocessing</h2>
<p class="p">The following deprecated templates and modes have been removed in topic pull stylesheets:</p>
<ul class="ul">
<li class="li">inherit</li>
<li class="li">get-stuff</li>
<li class="li">verify-type-attribute</li>
<li class="li">classval</li>
<li class="li">getshortdesc</li>
<li class="li">getlinktext</li>
<li class="li">blocktext</li>
<li class="li">figtext</li>
<li class="li">tabletext</li>
<li class="li">litext</li>
<li class="li">fntext</li>
<li class="li">dlentrytext</li>
<li class="li">firstclass</li>
<li class="li">invalid-list-item</li>
<li class="li">xref</li>
</ul>
</section>
<section class="section"><h2 class="title sectiontitle">PDF2</h2>
<p class="p">The following deprecated items are no longer supported in the PDF transform:</p>
<ul class="ul">
<li class="li">Support for the beta version of DITA, available from IBM before the OASIS standard was created in 2005.</li>
<li class="li">Support for the "bkinfo" demo plug-in, used to support book metadata before OASIS created the BookMap format
in 2007.</li>
<li class="li">Support for <span class="ph filepath">layout-masters.xml</span> configuration. Plug-ins should use the
<code class="ph codeph">createDefaultLayoutMasters</code> template instead.</li>
</ul>
<p class="p">The following extension-points have been added:</p>
<ul class="ul">
<li class="li"><code class="ph codeph">dita.conductor.pdf2.param</code> to add XSLT parameters to XSL FO transformation.</li>
</ul>
<p class="p">Custom PDF2 shell stylesheets need to be revised to not include separate IBM and OASIS DITA stylesheets. The
<span class="ph filepath"><var class="keyword varname">*</var>_1.0.xsl</span> stylesheets have been removed and their imports must be
removed from shell stylesheets.</p>
<p class="p">The following template modes have been deprecated:</p>
<ul class="ul">
<li class="li">toc-prefix-text</li>
<li class="li">toc-topic-text</li>
</ul>
<p class="p">The following named templates have been removed:</p>
<ul class="ul">
<li class="li">processTopic</li>
<li class="li">createMiniToc</li>
<li class="li">processTopicTitle</li>
<li class="li">createTopicAttrsName</li>
<li class="li">processConcept</li>
<li class="li">processReference</li>
<li class="li">getTitle</li>
<li class="li">placeNoteContent</li>
<li class="li">placeImage</li>
<li class="li">processUnknowType</li>
<li class="li">insertReferenceTitle</li>
<li class="li">buildRelationships</li>
<li class="li">processTask</li>
</ul>
<p class="p">The main FO generation process now relies on the merging process to rewrite duplicate IDs. The default merging
process did this already in previous releases, but now also custom merging processes must fulfill the duplicate
ID rewrite requirement.</p>
</section>
<section class="section"><h2 class="title sectiontitle">XHTML</h2>
<p class="p">The following named templates have been deprecated:</p>
<ul class="ul">
<li class="li">make-index-ref</li>
</ul>
<p class="p">The following deprecated templates have been removed:</p>
<ul class="ul">
<li class="li">revblock-deprecated</li>
<li class="li">revstyle-deprecated</li>
<li class="li">start-revision-flag-deprecated</li>
<li class="li">end-revision-flag-deprecated</li>
<li class="li">concept-links</li>
<li class="li">task-links</li>
<li class="li">reference-links</li>
<li class="li">relinfo-links</li>
<li class="li">sort-links-by-role</li>
<li class="li">create-links</li>
<li class="li">add-linking-attributes</li>
<li class="li">add-link-target-attribute</li>
<li class="li">add-user-link-attributes</li>
</ul>
<p class="p">The removed templates have been replaced by other templates in earlier releases and plug-ins should be changed
to use the new templates.</p>
</section>
<section class="section"><h2 class="title sectiontitle">ODT</h2>
<p class="p">The following deprecated templates have been removed:</p>
<ul class="ul">
<li class="li">revblock-deprecated</li>
<li class="li">revstyle-deprecated</li>
<li class="li">start-revision-flag-deprecated</li>
<li class="li">end-revision-flag-deprecated</li>
</ul>
<p class="p">The removed templates have been replaced by other templates in earlier releases and plug-ins should be changed
to use the new templates.</p>
</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>

93
dita-ot-3.6/doc/topics/migrating-to-1.7.html Normal file
View file

@ -0,0 +1,93 @@
<!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="In DITA-OT 1.7, a new preprocessing step implements flagging for HTML-based output formats. PDF processing was corrected with regard to shortdesc 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."><meta name="keywords" content="deprecated features, dita.input, dita.input.dirname, dita.extname, XHTML, flagging-related templates, page-margin-left, page-margin-right"><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 1.7</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><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 class="active"><a href="../topics/migrating-to-1.7.html">To 1.7</a><ul><li><a href="../reference/flagging-migration.html">Flagging updates</a></li></ul></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 1.7</h1>
<div class="body refbody"><p class="shortdesc">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. </p>
<section class="section">
<p class="p">A new job status file <span class="ph filepath">.job.xml</span> has been introduced and replaces
<span class="ph filepath">dita.list</span> and <span class="ph filepath">dita.xml.properties</span> as the normative source for job
status. If you have custom processing which modifies the job properties, you should change your code to modify
<span class="ph filepath">.job.xml</span> instead.</p>
<p class="p">Support for the following deprecated properties has been removed:</p>
<ul class="ul">
<li class="li"><code class="ph codeph">dita.input</code></li>
<li class="li"><code class="ph codeph">dita.input.dirname</code></li>
<li class="li"><code class="ph codeph">dita.extname</code></li>
</ul>
<p class="p">Stylesheets for the following transformation types have moved to plug-in specific folders:</p>
<ul class="ul">
<li class="li"><span class="keyword option">docbook</span></li>
<li class="li"><span class="keyword option">eclipsecontent</span></li>
<li class="li"><span class="keyword option">troff</span></li>
<li class="li"><span class="keyword option">wordrtf</span></li>
</ul>
<p class="p">If custom plug-ins have hard coded paths to these stylesheets, update references to use either
<code class="ph codeph">plugin</code> URIs in <code class="ph codeph">xsl:import</code> instructions or use <code class="ph codeph">dita.plugin.*</code>
Ant properties.</p>
<p class="p">The integration process has been changed to use strict mode by default. For old plug-ins which are not valid,
<span class="keyword">lax</span> processing mode can still be used.</p>
<p class="p">Plug-ins that use the <code class="ph codeph">MessageUtils</code> Java class must use <code class="ph codeph">getInstance</code> method to
access the <code class="ph codeph">MessageUtils</code> instance, as <code class="ph codeph">getMessage</code> methods have been changed to
instance methods.</p>
</section>
<section class="section"><h2 class="title sectiontitle">Preprocessing</h2>
<p class="p">The preprocessing Ant dependency chain has been cleaned up. Tasks no longer depend on the previous task in the
default chain, but rather the whole preprocess dependency chain is defined by the <code class="ph codeph">preprocess</code>
task.</p>
</section>
<section class="section"><h2 class="title sectiontitle">HTML</h2>
<p class="p">Core TOC generation has been moved to a separate XSLT stylesheet
<span class="ph filepath">xsl/map2htmtoc/map2htmlImpl.xsl</span> and the new templates use the mode <code class="ph codeph">toc</code>.
Plug-ins which override HTML TOC processing should change the map processing templates to <code class="ph codeph">toc</code>
mode.</p>
</section>
<section class="section"><h2 class="title sectiontitle">HTML and extended transformation types</h2>
<p class="p">Flagging logic has been pulled out of the core X/HTML code and moved to a preprocess step. This significantly
simplifies and optimizes the X/HTML code, while making flagging logic available to any other transformation
type. The new preprocess step implements all flagging logic; for each active flag, it adds a DITA-OT specific
hint into the intermediate topics (implemented as a specialization of the DITA &lt;foreign&gt; element). As part
of this change, all flagging-related templates in the XHTML code (such as start-flagit and gen-style) are
deprecated.</p>
<p class="p">If you override the X/HTML transforms, you may need to update your overrides to use the new flagging logic. In
most cases this just means deleting calls to the deprecated templates; in some cases, the calls can be replaced
with 2 lines to process flags in new places. You should compare your override to the updated XHTML code and
update as needed. See
<a class="xref" href="../reference/flagging-migration.html" title="This topic is primarily of interest to developers with XHTML transform overrides written prior to DITA-OT 1.7. Due to significant changes in the flagging process with the 1.7 release, some changes may be needed to make overrides work properly with DITAVAL-based flagging. The new design is significantly simpler than the old design; in many cases, migration will consist of deleting old code that is no longer needed.">XHTML migration for flagging updates in DITA-OT 1.7</a> for details.</p>
<p class="p">Plug-ins that provide support for new transforms need to ensure that they properly support the DITA
&lt;foreign&gt; element, which should be ignored by default; if so, this change will have no immediate impact.
Support for flagging new transformation types may be more easily added based on this update, because there is no
need to re-implement flagging logic, but this is not required. See
<a class="xref" href="../reference/preprocess-flagging.html" title="Beginning with DITA-OT 1.7, flagging support is implemented as a common flag-module preprocessing step. The module evaluates the DITAVAL against all flagging attributes, and adds DITA-OT–specific hints to the topic when flags are active. Any extended transformation type may use these hints to support flagging without adding logic to interpret the DITAVAL.">Flagging (flag-module)</a> for details on how to add flagging support.</p>
</section>
<section class="section"><h2 class="title sectiontitle">PDF</h2>
<p class="p">The following deprecated XSLT variables have been removed:</p>
<ul class="ul">
<li class="li"><code class="ph codeph">page-margin-left</code></li>
<li class="li"><code class="ph codeph">page-margin-right</code></li>
</ul>
<p class="p">XSLT stylesheets have been split to separate specialization topic code and new <code class="ph codeph">xsl:import</code>
instructions have been added to <span class="ph filepath">topic2fo.xsl</span>. Plug-ins which define their own shell
stylesheet should be revised to import all the required stylesheet modules.</p>
<p class="p">PDF processing used to replace topic <code class="ph codeph">shortdesc</code> with map <code class="ph codeph">shortdesc</code>, but this
behavior was incorrect and was removed to comply with the DITA specification.</p>
<p class="p">A new <code class="ph codeph">#note-separator</code> variable string was added to facilitate customization.</p>
</section>
</div>
<nav role="navigation" class="related-links"><ul class="ullinks"><li class="link ulchildlink"><strong><a href="../reference/flagging-migration.html">XHTML migration for flagging updates in DITA-OT 1.7</a></strong><br>This topic is primarily of interest to developers with XHTML transform overrides written prior to DITA-OT 1.7. Due to significant changes in the flagging process with the 1.7 release, some changes may be needed to make overrides work properly with DITAVAL-based flagging. The new design is significantly simpler than the old design; in many cases, migration will consist of deleting old code that is no longer needed.</li></ul><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>

102
dita-ot-3.6/doc/topics/migrating-to-1.8.html Normal file
View file

@ -0,0 +1,102 @@
<!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="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."><meta name="keywords" content="deprecated features, dita.script.dir, dita.resource.dir, dita.empty, args.message.file, ImgUtils, artwork-preprocessor.xsl, otdita2fo_frontend.xsl, insertVariable.old, XSLT mode,, layout-masters-processing, toc-prefix-text, toc-topic-text, args.fo.include.rellinks, Legacy PDF, args.odt.include.rellinks, disableRelatedLinks"><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 1.8</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><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 class="active"><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 1.8</h1>
<div class="body refbody"><p class="shortdesc">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.</p>
<section class="section">
<p class="p">Stylesheets for the following transformation types have moved to plug-in specific folders:</p>
<ul class="ul">
<li class="li"><span class="keyword option">eclipsehelp</span></li>
<li class="li"><span class="keyword option">htmlhelp</span></li>
<li class="li"><span class="keyword option">javahelp</span></li>
<li class="li"><span class="keyword option">odt</span></li>
<li class="li"><span class="keyword option">xhtml</span></li>
</ul>
</section>
<section class="section"><h2 class="title sectiontitle">Preprocessing</h2>
<p class="p">The following deprecated Ant properties have been removed:</p>
<ul class="ul">
<li class="li"><code class="ph codeph">dita.script.dir</code>, use <code class="ph codeph">${dita.plugin.<var class="keyword varname">id</var>.dir}</code> instead</li>
<li class="li"><code class="ph codeph">dita.resource.dir</code>, use <code class="ph codeph">${dita.plugin.org.dita.base.dir}/resource</code>
instead</li>
<li class="li"><code class="ph codeph">dita.empty</code></li>
<li class="li"><code class="ph codeph">args.message.file</code></li>
</ul>
</section>
<section class="section"><h2 class="title sectiontitle">XHTML</h2>
<p class="p">XSLT Java extension <code class="ph codeph">ImgUtils</code> has been removed from stylesheets and been replaced with
preprocessing module <code class="ph codeph">ImageMetadataModule</code>. The old <code class="ph codeph">ImgUtils</code> Java classes are
still included in the build.</p>
</section>
<section class="section"><h2 class="title sectiontitle">PDF</h2>
<p class="p">The following deprecated XSLT stylesheets have been removed:</p>
<ul class="ul">
<li class="li"><span class="ph filepath">artwork-preprocessor.xsl</span></li>
<li class="li"><span class="ph filepath">otdita2fo_frontend.xsl</span></li>
</ul>
<p class="p">The following deprecated XSLT templates have been removed:</p>
<ul class="ul">
<li class="li"><code class="ph codeph">insertVariable.old</code></li>
</ul>
<p class="p">The following deprecated XSLT modes have been removed:</p>
<ul class="ul">
<li class="li"><code class="ph codeph">layout-masters-processing</code></li>
<li class="li"><code class="ph codeph">toc-prefix-text</code>, use <code class="ph codeph">tocPrefix</code> mode instead</li>
<li class="li"><code class="ph codeph">toc-topic-text</code>, use <code class="ph codeph">tocText</code> mode instead</li>
</ul>
<p class="p">Link generation has been simplified by removing deprecated arguments in favor of
<code class="ph codeph">args.rellinks</code>. The following deprecated Ant properties have been removed:</p>
<ul class="ul">
<li class="li"><code class="ph codeph">args.fo.include.rellinks</code></li>
</ul>
<p class="p">The following XSLT parameters have been removed:</p>
<ul class="ul">
<li class="li"><code class="ph codeph">antArgsIncludeRelatedLinks</code></li>
<li class="li"><code class="ph codeph">disableRelatedLinks</code></li>
</ul>
<p class="p">A call to a named template <code class="ph codeph">pullPrologIndexTerms.end-range</code> has been added to
<code class="ph codeph">processTopic*</code> templates to handle topic wide index ranges.</p>
</section>
<section class="section"><h2 class="title sectiontitle">Legacy PDF</h2>
<p class="p">The following deprecated XSLT stylesheets have been removed:</p>
<ul class="ul">
<li class="li"><span class="ph filepath">dita2fo-shell_template.xsl</span></li>
<li class="li"><span class="ph filepath">topic2fo-shell.xsl</span></li>
</ul>
</section>
<section class="section"><h2 class="title sectiontitle">ODT</h2>
<p class="p">Link generation has been simplified by removing deprecated arguments in favor of
<code class="ph codeph">args.rellinks</code>. The following deprecated Ant properties have been removed:</p>
<ul class="ul">
<li class="li"><code class="ph codeph">args.odt.include.rellinks</code></li>
</ul>
<p class="p">The following XSLT parameters have been added:</p>
<ul class="ul">
<li class="li"><code class="ph codeph">include.rellinks</code></li>
</ul>
<p class="p">The following XSLT parameters have been removed:</p>
<ul class="ul">
<li class="li"><code class="ph codeph">disableRelatedLinks</code></li>
</ul>
</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>

62
dita-ot-3.6/doc/topics/migrating-to-2.0.html Normal file
View file

@ -0,0 +1,62 @@
<!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="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 dita command simplifies distribution of plugins by allowing installation from a URL."><meta name="keywords" content=", as, command, dita, plug-ins, uninstalling, removing, deinstalling, XSLT, 2.0, Customization directory"><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 2.0</title></head><body id="migrating-to-2.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><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 class="active"><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 2.0</h1>
<div class="body refbody"><p class="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 <span class="keyword cmdname">dita</span> command simplifies distribution of
plugins by allowing installation from a URL.
</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 2.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/2.0/readme/changes/rel2.0.html" target="_blank" rel="external noopener">DITA-OT 2.0 Release Notes</a>.</div>
</section>
<div class="bodydiv refbodydiv">
<section class="section"><h2 class="title sectiontitle">All transformations — variable typing</h2>
<p class="p">XSLT stylesheets were converted to XSLT 2.0. With that change, variable types were also implemented. Plug-ins
that change template variable values will need to make the following changes:</p>
<ul class="ul">
<li class="li">Declare the same types defined in the default templates with <code class="keyword markupname xmlatt">@as</code>.</li>
<li class="li">Ensure that the generated values conform to the declared type.</li>
</ul>
</section>
<div class="example">
<p class="p">For example:</p>
<pre class="pre codeblock language-xml"><code>&lt;xsl:variable name="urltest"&gt;
&lt;xsl:variable name="urltest" <strong class="ph b">as="xs:boolean"</strong>&gt;</code></pre>
</div>
<section class="section"><h2 class="title sectiontitle">All transformations — refactoring</h2>
<p class="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>
</div>
<section class="section"><h2 class="title sectiontitle">HTML5</h2>
<p class="p">A new <span class="keyword option">HTML5</span> 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>
<div class="note note note_note"><span class="note__title">Note:</span> The <span class="keyword option">HTML5</span> 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
<a class="xref" href="migrating-to-2.2.html" title="In DITA-OT 2.2, the HTML5 transformation was refactored as its own plug-in and separate plug-ins were created for each of the rendering engine-specific PDF transformations.">Migrating to release 2.2</a>.</div>
</section>
<section class="section"><h2 class="title sectiontitle">Plug-in installation and distribution</h2>
<p class="p">Plug-ins can now be installed or uninstalled from a ZIP archive using the new <span class="keyword cmdname">dita</span> command.
Plug-ins can also be installed from a referenced URL. See
<a class="xref" href="../parameters/dita-command-arguments.html" title="The dita command takes mandatory arguments to process DITA content. Subcommands can be used to manage plug-ins, or print information about the current configuration. A series of options are available to modify the command behavior or specify additional configuration parameters.">Arguments and options for the dita command</a>.</p>
</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>

137
dita-ot-3.6/doc/topics/migrating-to-2.1.html Normal file
View file

@ -0,0 +1,137 @@
<!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="In DITA-OT 2.1, the insertVariable template was deprecated for PDF transformations and should be replaced with the getVariable template. Various dita.out.map.* targets have been deprecated in favor of updated dita.map.* equivalents."><meta name="keywords" content=", ph, keyword, cite, dt, term, indexterm, href, deprecated features, build target, help, imagefile, image.list, htmlfile, html.list, target, copy-subsidiary, copy-subsidiary-check, extension points, depend.preprocess.copy-subsidiary.pre, PDF,, insertVariable, variable, keydefs, KEYREF-FILE, displaytext, keys, target, template, pull-in-title, common-processing-phrase-within-link, dita.out.map.xhtml.toc, targets, dita.out.map.htmlhelp.*, dita.out.map.javahelp.*, args.odt.img.embed"><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 2.1</title></head><body id="migrating-to-2.1"><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><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 class="active"><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 2.1</h1>
<div class="body refbody"><p class="shortdesc">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.</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 2.1 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/2.1/release-notes/" target="_blank" rel="external noopener">DITA-OT 2.1 Release Notes</a>.</div>
</section>
<section class="section">
<p class="p">The custom<samp class="ph systemoutput sysout">FileUtils</samp> code used to handle input and output in earlier versions of
DITA-OT has been replaced with the
<a class="xref" href="http://commons.apache.org/proper/commons-io/" target="_blank" rel="external noopener">Apache Commons
IO</a> utilities library. </p>
</section>
<section class="section"><h2 class="title sectiontitle">Deprecated targets</h2>
<p class="p">The following build targets have been deprecated and will be removed in an upcoming release:</p>
<ul class="ul">
<li class="li">The <code class="ph codeph">help</code> target that includes a reference to the current DITA-OT version during the build
process.</li>
</ul>
</section>
<section class="section"><h2 class="title sectiontitle">Preprocessing</h2>
<p class="p">The following Ant properties and generated list files have been deprecated:</p>
<ul class="ul">
<li class="li"><span class="keyword parmname">imagefile</span> property and <code class="ph codeph">image.list</code> file</li>
<li class="li"><span class="keyword parmname">htmlfile</span> property and <code class="ph codeph">html.list</code> file</li>
</ul>
<p class="p">The following pre-processing targets and extension points have been deprecated:</p>
<ul class="ul">
<li class="li">The <code class="ph codeph">copy-subsidiary</code> target used to copy subsidiary files</li>
<li class="li">The <code class="ph codeph">copy-subsidiary-check</code> target used to check for subsidiary files</li>
<li class="li">The <span class="keyword parmname">depend.preprocess.copy-subsidiary.pre</span> extension point used to insert an Ant target
before the <code class="ph codeph">copy-subsidiary</code> step in the pre-processing stage.</li>
</ul>
<p class="p">A new<samp class="ph systemoutput sysout">dita.parser</samp> extension point has been added to allow plug-ins to contribute a
custom parser for DITA files. 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.</p>
</section>
<section class="section"><h2 class="title sectiontitle">PDF</h2>
<p class="p">The following template has been deprecated:</p>
<ul class="ul">
<li class="li"><code class="ph codeph">insertVariable</code>, use <code class="ph codeph">getVariable</code> instead</li>
</ul>
<p class="p">Calls to that template will result in warnings in the build log.</p>
<p class="p">To update your plug-in, make the following changes:</p>
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;xsl:call-template name="<span class="ph line-through">insertVariable</span><strong class="ph b">getVariable</strong>"&gt;
&lt;xsl:with-param name="<span class="ph line-through">theVariableID</span><strong class="ph b">id</strong>" select="<var class="keyword varname">var-id</var>"/&gt;
&lt;xsl:with-param name="<span class="ph line-through">theParameters</span><strong class="ph b">params</strong>"&gt;
<var class="keyword varname">params</var>
&lt;/xsl:with-param&gt;
&lt;/xsl:call-template&gt;</code></pre>
</section>
<section class="section"><h2 class="title sectiontitle">HTML-based output formats</h2>
<div class="p">The <var class="keyword varname">keydefs</var> variable and the following XSL parameters have been deprecated:
<ul class="ul">
<li class="li"><span class="keyword parmname">KEYREF-FILE</span></li>
<li class="li"><span class="keyword parmname">displaytext</span></li>
<li class="li"><span class="keyword parmname">keys</span></li>
<li class="li"><span class="keyword parmname">target</span></li>
</ul>
</div>
<div class="p">The following template modes have been deprecated:
<ul class="ul">
<li class="li"><code class="ph codeph">pull-in-title</code></li>
<li class="li"><code class="ph codeph">common-processing-phrase-within-link</code></li>
</ul>
</div>
</section>
<section class="section"><h2 class="title sectiontitle">XHTML</h2>
<p class="p">The <code class="ph codeph">dita.<strong class="ph b">out.</strong>map.xhtml.toc</code> target has been deprecated and should be replaced with the
updated <code class="ph codeph">dita.map.xhtml.toc</code> equivalent.</p>
<p class="p">Keydef processing has been removed from the XHTML rendering code. Keys are now resolved in one preprocessing
step, whereas in earlier versions of DITA-OT, the XHTML code returned to the <span class="ph filepath">keydef.xml</span>
file to look up targets for phrase elements and pull in text when needed.</p>
<p class="p">This change affects non-linking elements that can’t take <code class="keyword markupname xmlatt">@href</code> attributes, such as
<code class="keyword markupname xmlelement">&lt;ph&gt;</code>, <code class="keyword markupname xmlelement">&lt;keyword&gt;</code>, <code class="keyword markupname xmlelement">&lt;cite&gt;</code>,
<code class="keyword markupname xmlelement">&lt;dt&gt;</code>, <code class="keyword markupname xmlelement">&lt;term&gt;</code>, and <code class="keyword markupname xmlelement">&lt;indexterm&gt;</code> (when
<code class="ph codeph">$INDEXSHOW</code> is active).</p>
</section>
<section class="section"><h2 class="title sectiontitle">HTMLHelp</h2>
<p class="p">The <code class="ph codeph">dita.<strong class="ph b">out.</strong>map.htmlhelp.*</code> targets have been deprecated and should be replaced with
the updated <code class="ph codeph">dita.map.htmlhelp.*</code> equivalents:</p>
<ul class="ul">
<li class="li"><code class="ph codeph">dita.out.map.htmlhelp.hhp</code>, use <code class="ph codeph">dita.map.htmlhelp.hhp</code> instead</li>
<li class="li"><code class="ph codeph">dita.out.map.htmlhelp.hhc</code>, use <code class="ph codeph">dita.map.htmlhelp.hhc</code> instead</li>
<li class="li"><code class="ph codeph">dita.out.map.htmlhelp.hhk</code>, use <code class="ph codeph">dita.map.htmlhelp.hhk</code> instead</li>
</ul>
</section>
<section class="section"><h2 class="title sectiontitle">JavaHelp</h2>
<p class="p">The <code class="ph codeph">dita.<strong class="ph b">out.</strong>map.javahelp.*</code> targets have been deprecated and should be replaced with
the updated <code class="ph codeph">dita.map.javahelp.*</code> equivalents:</p>
<ul class="ul">
<li class="li"><code class="ph codeph">dita.out.map.javahelp.toc</code>, use <code class="ph codeph">dita.map.javahelp.toc</code> instead</li>
<li class="li"><code class="ph codeph">dita.out.map.javahelp.map</code>, use <code class="ph codeph">dita.map.javahelp.map</code> instead</li>
<li class="li"><code class="ph codeph">dita.out.map.javahelp.set</code>, use <code class="ph codeph">dita.map.javahelp.set</code> instead</li>
<li class="li"><code class="ph codeph">dita.out.map.javahelp.index</code>, use <code class="ph codeph">dita.map.javahelp.index</code> instead</li>
</ul>
</section>
<section class="section"><h2 class="title sectiontitle">OpenDocument Text</h2>
<p class="p">Support for the <span class="keyword parmname">args.odt.img.embed</span> parameter has been removed from OpenDocument Text
transformations. 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.</p>
</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>

64
dita-ot-3.6/doc/topics/migrating-to-2.2.html Normal file
View file

@ -0,0 +1,64 @@
<!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="In DITA-OT 2.2, the HTML5 transformation was refactored as its own plug-in and separate plug-ins were created for each of the rendering engine-specific PDF transformations."><meta name="keywords" content=", toc, preface, frontmatter, bookmap, deprecated features, classes, .notetitle, user.input.file, user.input.dir, InputMapDir, RenderX, plug-in, Antenna House, Apache FOP, table of contents, PDF"><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 2.2</title></head><body id="migrating-to-2.2"><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><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 class="active"><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 2.2</h1>
<div class="body refbody"><p class="shortdesc">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.
</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 2.2 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/2.2/release-notes/" target="_blank" rel="external noopener">DITA-OT 2.2 Release Notes</a>.</div>
</section>
<section class="section"><h2 class="title sectiontitle">HTML5</h2>
<p class="p">The <span class="keyword option">HTML5</span> transformation introduced in release 2.0 as part of the <span class="keyword option">XHTML</span>
plug-in has been moved to a separate <span class="keyword option">HTML5</span> plug-in. Customizations that extended the previous
HTML5 output under the <span class="keyword option">XHTML</span> plug-in will probably need to be refactored on the new HTML5
plug-in.</p>
<p class="p">Note title processing has been revised to use a common <code class="ph codeph">note__title</code> class for note elements of
all types. The legacy <code class="ph codeph"><var class="keyword varname">{$type}</var>title</code> classes (such as
<code class="ph codeph">.notetitle</code>, <code class="ph codeph">.cautiontitle</code>, <code class="ph codeph">.tiptitle</code>, etc.) are included
for backwards compatibility, but are deprecated and will be removed in an upcoming release. Stylesheets that
apply formatting overrides to note titles should be revised to replace the deprecated class selectors with the
equivalent descendant selectors, for example <code class="ph codeph">.note_note .note__title</code>, <code class="ph codeph">.note_caution
.note__title</code>, <code class="ph codeph">.note_tip .note__title</code>, etc.</p>
</section>
<section class="section"><h2 class="title sectiontitle">PDF</h2>
<p class="p">Processing specific to Apache FOP, Antenna House Formatter, and RenderX XEP has been separated into separate
plug-ins for each of those rendering engines. Customizations that extended this processing might need to extend
the new <code class="ph codeph">org.dita.pdf2.fop</code>, <code class="ph codeph">org.dita.pdf2.axf</code>, or
<code class="ph codeph">org.dita.pdf2.xep</code> plug-ins.</p>
<p class="p">PDF customizations that are not specific to a rendering engine can continue to extend the
<code class="ph codeph">org.dita.pdf2</code> plug-in as before.</p>
<p class="p">The default format for page numbers in the table of contents (<code class="keyword markupname xmlelement">&lt;toc&gt;</code>) was switched to
roman to align with <code class="keyword markupname xmlelement">&lt;preface&gt;</code> and ensure consistent numbering styles for all
<code class="keyword markupname xmlelement">&lt;frontmatter&gt;</code> components in <code class="keyword markupname xmlelement">&lt;bookmap&gt;</code>. This prevents numbering
from switching back and forth between styles in bookmaps where the Preface follows the table of contents.
Earlier versions of DITA-OT produced numbering sequences like <code class="ph codeph">1,2,3,4,v,vi,7,8</code> in this use
case.</p>
</section>
<section class="section"><h2 class="title sectiontitle">Deprecated properties</h2>
<div class="p">The following Ant properties have been deprecated:
<ul class="ul">
<li class="li"><span class="keyword parmname">user.input.file</span>, use <span class="keyword parmname">user.input.file.uri</span> instead to specify the
input file system path</li>
<li class="li"><span class="keyword parmname">user.input.dir</span>, use <span class="keyword parmname">user.input.dir.uri</span> instead to specify the
input directory system path</li>
<li class="li"><span class="keyword parmname">InputMapDir</span>, use <span class="keyword parmname">InputMapDir.uri</span> instead to specify the input
map directory system path</li>
</ul></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>

140
dita-ot-3.6/doc/topics/migrating-to-2.3.html Normal file
View file

@ -0,0 +1,140 @@
<!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="In DITA-OT 2.3, HTML5 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 id variable that contains the entire message ID."><meta name="keywords" content="languages, supported, Chinese, English, Indonesian, Korean, I18N, PDF processing, metadata, chunking, effect of, tables, HTML5, PDF"><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 2.3</title></head><body id="migrating-to-2.3"><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><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 class="active"><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 2.3</h1>
<div class="body refbody"><p class="shortdesc">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.</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 2.3 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/2.3/release-notes/" target="_blank" rel="external noopener">DITA-OT 2.3 Release Notes</a>.</div>
</section>
<section class="section"><h2 class="title sectiontitle">HTML5</h2>
<p class="p">The <span class="keyword option">HTML5</span> table processing has been refactored to use valid HTML5 markup, HTML5 best
practices, and better CSS properties for styling.
<a class="xref" href="https://en.bem.info/methodology/" target="_blank" rel="external noopener">BEM</a>-style CSS classes are
now generated with the name of the containing element, the name of the attribute, and the value of the
attribute. </p>
<p class="p">Common CSS files are now generated using separate modules for each DITA domain, implemented as
<a class="xref" href="http://sass-lang.com" target="_blank" rel="external noopener">Sass</a> partials to better support extensions with CSS frameworks, custom plug-ins and future
toolkit versions.</p>
</section>
<section class="section"><h2 class="title sectiontitle">HTML-based formats</h2>
<p class="p">The XSLT <code class="ph codeph">tm-area</code> named template, which used to toggle rendering of trademark symbols in US
English and Asian languages (Japanese, Korean, and both Chinese) but ignore them in all other languages, has
been deprecated. Trademark symbols are now rendered uniformly for all languages and the template will be removed
in an upcoming release.</p>
<p class="p" id="migrating-to-2.3__2191">In previous releases, short descriptions in <code class="keyword markupname xmlelement">&lt;abstract&gt;</code> elements were rendered
as division elements (<code class="keyword markupname xmlelement">&lt;div&gt;</code>), rather than paragraphs (<code class="keyword markupname xmlelement">&lt;p&gt;</code>).
Processing has been revised to ensure that short descriptions are consistently rendered as paragraphs,
regardless of whether they appear in <code class="keyword markupname xmlelement">&lt;abstract&gt;</code> elements. Users who have previously
implemented custom CSS rules to style <code class="ph codeph">div.shortdesc</code> like paragraphs should be able to remove
these rules.</p>
</section>
<section class="section"><h2 class="title sectiontitle">PDF</h2>
<p class="p">The <code class="ph codeph">antiquewhite</code> background color has been removed from table heads and key column contents in
<code class="keyword markupname xmlelement">&lt;simpletable&gt;</code> and <code class="keyword markupname xmlelement">&lt;properties&gt;</code> tables to synchronize
presentation with <code class="keyword markupname xmlelement">&lt;choicetable&gt;</code> and provide a more uniform customization baseline between
PDF output and HTML-based formats.</p>
<p class="p" id="migrating-to-2.3__2179">PDF: The I18N Java and XSLT processing code has been merged into single task. This eliminated the
need for a <span class="ph filepath">stage3.fo</span> file in the temporary directory; instead,
<span class="ph filepath">topic.fo</span> is generated directly from <span class="ph filepath">stage2.fo</span>. If custom plug-ins
were implemented to handle <span class="ph filepath">stage3.fo</span>, they would need to be updated. </p>
<div class="p">Localization variables that are no longer used in PDF processing have been deprecated and will be removed in an
upcoming release. PDF customization plug-ins that make use of these variables should plan to refactor
accordingly:
<ul class="ul">
<li class="li">Back button title</li>
<li class="li">Contents button title</li>
<li class="li">Forward button title</li>
<li class="li">Index button title</li>
<li class="li">Index multiple entries separator</li>
<li class="li">Main page button title</li>
<li class="li">Next page button title</li>
<li class="li">Online help prefix</li>
<li class="li">Online Help Search Method And</li>
<li class="li">Online Help Search Method Field</li>
<li class="li">Online Help Search Method Or</li>
<li class="li">Previous page button title</li>
<li class="li">Search button title</li>
<li class="li">Search Case Sensitive Switch</li>
<li class="li">Search Excluded Stop Words Message</li>
<li class="li">Search Highlight Switch</li>
<li class="li">Search index button title</li>
<li class="li">Search index field title</li>
<li class="li">Search index next button title</li>
<li class="li">Search Search Give No Results Message</li>
<li class="li">Search Search in Progress Message</li>
<li class="li">Search Stopped Message</li>
<li class="li">Search text button title</li>
<li class="li">Search text field title</li>
<li class="li">Search title</li>
<li class="li">Search Whole Words Switch</li>
<li class="li">Untitled section</li>
</ul>
</div>
<div class="note note note_note"><span class="note__title">Note:</span> Most of these variables were never used by the PDF process, and most were not supported (or localized) for
any language other than English.</div>
</section>
<section class="section"><h2 class="title sectiontitle">Deprecated properties and targets</h2>
<div class="p">The following Ant properties have been deprecated:
<ul class="ul">
<li class="li"><span class="keyword parmname">conreffile</span></li>
</ul>
</div>
<div class="p">The following preprocessing targets have been deprecated:
<ul class="ul">
<li class="li"><span class="keyword parmname">conref-check</span></li>
<li class="li"><span class="keyword parmname">coderef</span></li>
</ul>
</div>
</section>
<section class="section"><h2 class="title sectiontitle">Pre-processing</h2>
<p class="p" id="migrating-to-2.3__2207">The order of the <code class="ph codeph">chunk</code> and <code class="ph codeph">move-meta-entries</code> pre-processing stages
has been switched so that <code class="ph codeph">chunk</code> comes first. This ensures that metadata is properly pulled or
pushed into the chunked version of DITA topics. </p>
</section>
<section class="section"><h2 class="title sectiontitle">Generating error messages</h2>
<p class="p">Previously, the XSLT <code class="ph codeph">output-message</code> named template for generating error messages combined a
global <code class="ph codeph">msgprefix</code> variable and two parameters to determine the actual message ID. This function
has been updated to use a single <code class="ph codeph">id</code> variable that contains the entire message ID.</p>
<div class="p">Plug-ins that make use of the <code class="ph codeph">output-message</code> function should be updated to use the single
<code class="ph codeph">id</code> variable, as
in:<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;xsl:call-template name="output-message"&gt;
&lt;xsl:with-param name="id" select="'FULLMESSAGENUMBER'"/&gt;
&lt;xsl:with-param name="msgparams"&gt;optional-message-parameters&lt;/xsl:with-param&gt;
&lt;/xsl:call-template&gt;</code></pre>
</div>
<p class="p">The <code class="ph codeph">msgprefix</code> XSL variable (“DOTX”) has been deprecated and will be removed in an upcoming
release.</p>
</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>

99
dita-ot-3.6/doc/topics/migrating-to-2.4.html Normal file
View file

@ -0,0 +1,99 @@
<!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="In DITA-OT 2.4, the HTML5 transformation was refactored as an independent plug-in that no longer depends on the XHTML plug-in."><meta name="keywords" content="deprecated features, classes, .notetitle, 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 2.4</title></head><body id="migrating-to-2.4"><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><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 class="active"><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 2.4</h1>
<div class="body refbody"><p class="shortdesc">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. </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 2.4 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/2.4/release-notes/" target="_blank" rel="external noopener">DITA-OT 2.4 Release Notes</a>.</div>
</section>
<section class="section"><h2 class="title sectiontitle">HTML5</h2>
<ul class="ul">
<li class="li">
<div class="div" id="migrating-to-2.4__24-html5-split">
<p class="p">The <span class="keyword option">HTML5</span> transformation introduced in release 2.0 as part of the <span class="keyword option">XHTML</span>
plug-in was moved to a separate <span class="keyword option">HTML5</span> plug-in in release 2.2, but that version of the
<span class="keyword option">HTML5</span> transformation still depended on the <span class="keyword option">XHTML</span> plug-in for certain
common processing.</p>
<p class="p">In release 2.4, all dependencies between <span class="keyword option">HTML5</span> and <span class="keyword option">XHTML</span> have been
removed to ensure that HTML5 processing can be further refactored in the future without affecting XHTML
output, or other HTML-based transformations such as <span class="keyword option">eclipsehelp</span>,
<span class="keyword option">htmlhelp</span> or <span class="keyword option">javahelp</span>.</p>
</div>
<p class="p">Customizations that extended the previous HTML5 output under the <span class="keyword option">XHTML</span> plug-in (as
provided in releases 2.0 and 2.1) or the <span class="keyword option">HTML5</span> plug-in that shipped with release 2.2 will
need to be refactored to build on the new HTML5 plug-in.</p></li>
<li class="li">
<p class="p">Note title processing was revised in release 2.2 to include a common <code class="ph codeph">note__title</code> class for
note elements of all types. The legacy <code class="ph codeph"><var class="keyword varname">{$type}</var>title</code> classes (such as
<code class="ph codeph">.notetitle</code>, <code class="ph codeph">.cautiontitle</code>, <code class="ph codeph">.tiptitle</code>, etc.) were
included in release 2.2 for backwards compatibility, but have now been removed in release 2.4.</p>
<p class="p">Stylesheets that apply formatting overrides to note titles should be revised to replace the deprecated
class selectors with the equivalent descendant selectors, for example:</p>
<ul class="ul">
<li class="li"><code class="ph codeph">.note_note .note__title</code></li>
<li class="li"><code class="ph codeph">.note_caution .note__title</code></li>
<li class="li"><code class="ph codeph">.note_tip .note__title</code></li>
</ul>
</li>
</ul>
</section>
<section class="section" id="migrating-to-2.4__24-legacy-plugin-removal"><h2 class="title sectiontitle">Legacy plug-ins removed</h2>
<p class="p">DITA-OT 2.4 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-2.4__24-legacy-plugin-removal__entry__1">Plug-in </th>
<th class="entry colsep-0 rowsep-1" id="migrating-to-2.4__24-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-2.4__24-legacy-plugin-removal__entry__1">DocBook</td>
<td class="entry colsep-0 rowsep-1" headers="migrating-to-2.4__24-legacy-plugin-removal__entry__2">
<a class="xref" href="https://github.com/dita-ot/org.dita.docbook" target="_blank" rel="external noopener">https://github.com/dita-ot/org.dita.docbook</a></td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="migrating-to-2.4__24-legacy-plugin-removal__entry__1">Eclipse Content</td>
<td class="entry colsep-0 rowsep-1" headers="migrating-to-2.4__24-legacy-plugin-removal__entry__2">
<a class="xref" href="https://github.com/dita-ot/org.dita.eclipsecontent" target="_blank" rel="external noopener">https://github.com/dita-ot/org.dita.eclipsecontent</a></td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="migrating-to-2.4__24-legacy-plugin-removal__entry__1">OpenDocument Text</td>
<td class="entry colsep-0 rowsep-1" headers="migrating-to-2.4__24-legacy-plugin-removal__entry__2">
<a class="xref" href="https://github.com/dita-ot/org.dita.odt" target="_blank" rel="external noopener">https://github.com/dita-ot/org.dita.odt</a></td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="migrating-to-2.4__24-legacy-plugin-removal__entry__1">Word RTF</td>
<td class="entry colsep-0 rowsep-1" headers="migrating-to-2.4__24-legacy-plugin-removal__entry__2">
<a class="xref" href="https://github.com/dita-ot/org.dita.wordrtf" target="_blank" rel="external noopener">https://github.com/dita-ot/org.dita.wordrtf</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>
</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>

84
dita-ot-3.6/doc/topics/migrating-to-2.5.html Normal file
View file

@ -0,0 +1,84 @@
<!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="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."><meta name="keywords" content=", example, PDF, org.dita.pdf2.legacy, languages, right-to-left"><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 2.5</title></head><body id="migrating-to-2.5"><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><a href="../topics/migrating-to-3.0.html">To 3.0</a></li><li class="active"><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 2.5</h1>
<div class="body refbody"><p class="shortdesc">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.</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 2.5 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/2.5/release-notes/" target="_blank" rel="external noopener">DITA-OT 2.5 Release Notes</a>.</div>
</section>
<section class="section"><h2 class="title sectiontitle">Deprecated logging parameters</h2>
<p class="p">The <code class="ph codeph">args.debug</code> and <code class="ph codeph">args.logdir</code> properties have been deprecated and will be
removed in an upcoming version of DITA-OT.</p>
<ul class="ul">
<li class="li">
<p class="p">To enable debug logging, use <span class="keyword cmdname">dita</span>
<span class="keyword parmname">--debug</span>.</p>
<div class="note attention note_attention"><span class="note__title">Attention:</span> Debug logging requires additional resources and can slow down the build process, so it
should only be enabled when further details are required to diagnose problems.</div>
</li>
<li class="li">
<p class="p">To write the log to a file, use <span class="keyword cmdname">dita</span>
<span class="keyword parmname">--logfile</span>=<var class="keyword varname">file</var> or <span class="keyword cmdname">ant</span>
<span class="keyword parmname">-l</span>
<var class="keyword varname">file</var> and specify the path to the log file.</p>
<p class="p">Unless an absolute path is specified, the value will be interpreted relative to the current
directory.</p></li>
</ul>
</section>
<section class="section" id="migrating-to-2.5__25-pdf-changes"><h2 class="title sectiontitle">Default PDF style improvements</h2>
<p class="p">Several legacy styles have been modified or removed in the default PDF plug-in <code class="ph codeph">org.dita.pdf2</code>,
including the following:</p>
<div class="p">
<ul class="ul">
<li class="li">In task topics with only a single step, the step is now rendered as a simple block (rather than as a list
item without a label).</li>
<li class="li">Table containers now inherit the initial indentation (<code class="ph codeph">start-indent</code>) from the parent
elements.</li>
<li class="li">Borders and indentation have been removed from <code class="keyword markupname xmlelement">&lt;example&gt;</code> elements.</li>
<li class="li">Links are no longer italicized.</li>
<li class="li">Titles for related link lists have been standardized to use the <code class="ph codeph">common.title</code> attribute
set (which applies the <code class="ph codeph">sans-serif</code> font-family) and bold font weight.</li>
<li class="li">Several remaining occurrences of left/right borders, margins, padding, and text alignment now use the
corresponding start/end equivalents to better support right-to-left languages.</li>
</ul>
</div></section>
<section class="section" id="migrating-to-2.5__25-legacy-pdf-plugin"><h2 class="title sectiontitle">External plug-in for legacy PDF styling</h2>
<p class="p">If you have a custom PDF plug-in that explicitly depends on the previous default settings for the
aforementioned styles, the <code class="ph codeph">org.dita.pdf2.legacy</code> plug-in can be used to restore the pre–2.5
styles.</p>
<table class="table table-hover frame-none"><caption></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-2.5__25-legacy-pdf-plugin__entry__1">Plug-in </th>
<th class="entry colsep-0 rowsep-1" id="migrating-to-2.5__25-legacy-pdf-plugin__entry__2">Source code location</th>
</tr>
</thead><tbody class="tbody">
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="migrating-to-2.5__25-legacy-pdf-plugin__entry__1"><code class="ph codeph">org.dita.pdf2.legacy</code></td>
<td class="entry colsep-0 rowsep-1" headers="migrating-to-2.5__25-legacy-pdf-plugin__entry__2">
<a class="xref" href="https://github.com/dita-ot/org.dita.pdf2.legacy" target="_blank" rel="external noopener">https://github.com/dita-ot/org.dita.pdf2.legacy</a></td>
</tr>
</tbody></table>
<p class="p">To install the legacy PDF 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.pdf2.legacy/archive/2.5.zip</span></code></pre>
<div class="note attention note_attention"><span class="note__title">Attention:</span> Only install the legacy PDF plug-in if you have a custom PDF plug-in that requires the
pre–2.5 styles. If your plug-in was designed for DITA-OT 2.4 and does not override these settings, there is no
need to install the legacy PDF plug-in.</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>

98
dita-ot-3.6/doc/topics/migrating-to-3.0.html Normal file
View file

@ -0,0 +1,98 @@
<!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">&lt;xsl:stylesheet version="1.0"&gt;</code> in custom
plug-in stylesheets to at least <code class="ph codeph">&lt;xsl:stylesheet version="2.0"&gt;</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>

73
dita-ot-3.6/doc/topics/migrating-to-3.1.html Normal file
View file

@ -0,0 +1,73 @@
<!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.1 includes support for DITA 1.3 SVG domain elements, enhanced codeblock processing, and incremental improvements to Lightweight DITA processing and PDF output."><meta name="keywords" content=", codeblock, param, if:set, unless:set, if, outputclass, deprecated features, property, dost.class.path, xml.catalog.files, Lightweight DITA, XSLT, Ant, DITA 1.3, SVG domain, SVG, catalog, xml.catalog.path"><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.1</title></head><body id="migrating-to-3.1"><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 class="active"><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 to release 3.1</h1>
<div class="body refbody"><p class="shortdesc">DITA-OT 3.1 includes <span class="ph" id="migrating-to-3.1__summary">support for DITA 1.3 SVG domain elements, enhanced
<code class="keyword markupname xmlelement">&lt;codeblock&gt;</code> processing, and incremental improvements to Lightweight DITA processing and
PDF output</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.1 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.1/release-notes/" target="_blank" rel="external noopener">DITA-OT 3.1 Release Notes</a>.</div>
</section>
<section class="section"><h2 class="title sectiontitle">Custom if/unless attributes in Ant scripts</h2>
<p class="p">Ant scripts for DITA-OT builds now make use of <code class="keyword markupname xmlatt">@if:set</code> and <code class="keyword markupname xmlatt">@unless:set</code>
attributes in the Ant namespace, which can be used to control whether parameters are passed to XSLT modules.
These attributes replace custom implementations of <code class="ph codeph">if</code> and <code class="ph codeph">unless</code> logic
introduced before Ant had this capability.</p>
<div class="p">If your plug-ins include Ant scripts that use <code class="keyword markupname xmlatt">@if</code> or <code class="keyword markupname xmlatt">@unless</code> on
<code class="keyword markupname xmlelement">&lt;param&gt;</code> elements that pass XSLT parameters, add the following namespace attributes to
the root project:
<ul class="ul">
<li class="li"><code class="keyword markupname xmlnsname">xmlns:if</code>=<code class="ph codeph">"ant:if"</code></li>
<li class="li"><code class="keyword markupname xmlnsname">xmlns:unless</code>=<code class="ph codeph">"ant:unless"</code></li>
</ul></div>
<p class="p">In custom Ant build files and in any files that supply parameters to existing DITA-OT XSLT modules, replace all
occurrences of <code class="ph codeph">if="property"</code> on <code class="keyword markupname xmlelement">&lt;param&gt;</code> elements with
<code class="ph codeph">if<strong class="ph b">:set</strong>="property"</code> (and <code class="ph codeph">unless</code> → <code class="ph codeph">unless<strong class="ph b">:set</strong></code>
respectively).</p>
<div class="p"><pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;root xmlns:if="ant:if" xmlns:unless="ant:unless"&gt;
&lt;param name="antProperty" expression="${antProperty}"
if<strong class="ph b">:set</strong>="antProperty"/&gt;
&lt;/root&gt;</code></pre></div>
<p class="p">For more information on passing parameters to existing XSLT steps, see
<a class="xref" href="../extension-points/plugin-extension-points-xslt-parameters.html" title="You can use these extension points to pass parameters into existing XSLT steps in both the pre-processing pipeline and DITA-OT transformation. The parameters generally will be available as global xsl:param values with XSLT overrides.">XSLT-parameter extension points</a>.</p>
</section>
<section class="section"><h2 class="title sectiontitle">Deprecated properties</h2>
<div class="sectiondiv">
<p class="p">As of DITA-OT 3.1, the Java class path is managed automatically, meaning you do not (and should not) use
explicit references to Java class paths in your build scripts. In particular, the old
<code class="ph codeph">dost.class.path</code> property has been deprecated and should not be used. If you are migrating
older plug-ins that manage their class path directly, you should remove any explicit class path configuration.
If your plug-in was not already using the <code class="ph codeph">dita.conductor.lib.import</code> extension point to
integrate its JAR dependencies you must add it.</p>
<p class="p">The effective DITA-OT class path is the combination of the JAR files in the main <span class="ph filepath">lib/</span>
directory and the plug-in-contributed JARs, which are listed in <span class="ph filepath">config/env.sh</span>. The
<span class="ph filepath">env.sh</span> file is updated automatically when plug-ins are installed or removed.</p>
</div>
<p class="p">The <code class="ph codeph">xml.catalog.files</code> property has been deprecated and should not be used. Replace any such
references with the <code class="ph codeph">xml.catalog.path</code> instead.</p>
</section>
<section class="section" id="migrating-to-3.1__pdf-line-numbers"><h2 class="title sectiontitle">PDF – Enabling line numbers in codeblocks </h2>
<p class="p">The <code class="ph codeph">codeblock.generate-line-number</code> template mode default has been changed to check for the
<code class="ph codeph">show-line-numbers</code> keyword in the <code class="keyword markupname xmlatt">@outputclass</code> attribute. Earlier versions of
DITA-OT required custom PDF plug-ins to override the template mode to return <code class="ph codeph">true()</code>. </p>
</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>

45
dita-ot-3.6/doc/topics/migrating-to-3.2.html Normal file
View file

@ -0,0 +1,45 @@
<!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.2 includes new command-line options, support for RELAX&nbsp;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."><meta name="keywords" content="deprecated features, Ant target, configuration-jar, Lightweight DITA, command line, RELAX&nbsp;NG parsing, security, TLS, registry, targets, deprecated, classpath"><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.2</title></head><body id="migrating-to-3.2"><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 class="active"><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 to release 3.2</h1>
<div class="body refbody"><p class="shortdesc">DITA-OT 3.2 includes <span class="ph" id="migrating-to-3.2__summary">new command-line options, support for RELAX&nbsp;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>.</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.2 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.2/release-notes/" target="_blank" rel="external noopener">DITA-OT 3.2 Release Notes</a>.</div>
</section>
<section class="section"><h2 class="title sectiontitle">Deprecated targets</h2>
<p class="p">The <span class="keyword parmname">configuration-jar</span> Ant target used during the plug-in integration process has been
deprecated and may be removed in an upcoming release. This was previously used to package additional
configuration files and properties into <span class="ph filepath">lib/dost-configuration.jar</span>, but recent versions of
DITA-OT include the <span class="ph filepath">config</span> directory in the classpath for this purpose, so the
configuration JAR is no longer necessary.</p>
</section>
<section class="section"><h2 class="title sectiontitle">Secure connections to the plug-in registry</h2>
<div class="note attention note_attention"><span class="note__title">Attention:</span> To ensure data integrity during the plug-in installation process, Transport Layer Security
(TLS) will soon be required to access the plug-in registry. If you are using DITA-OT 3.2 or 3.2.1 and are unable
to upgrade to the latest version, modify the <code class="ph codeph">registry</code> key in the
<span class="ph filepath">config/configuration.properties</span> file to switch the URI schema to
<code class="ph codeph">http<strong class="ph b">s</strong>://</code>, so the entry reads <code class="ph codeph">https://plugins.dita-ot.org/</code>.</div>
<p class="p">For more information, see
<a class="xref" href="plugins-registry.html" title="DITA-OT 3.2 supports a new plug-in registry that makes it easier to discover and install new plug-ins. The registry provides a searchable list of plug-ins at dita-ot.org/plugins.">Adding plug-ins via the registry</a>.</p>
</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>

101
dita-ot-3.6/doc/topics/migrating-to-3.3.html Normal file
View file

@ -0,0 +1,101 @@
<!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.3 includes new attribute sets for HTML5 customization, support for custom integration processing, rotated table cells in PDF output, and hazard statements in HTML output."><meta name="keywords" content="security, TLS, registry, tables, PDF"><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.3</title></head><body id="migrating-to-3.3"><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 class="active"><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 to release 3.3</h1>
<div class="body refbody"><p class="shortdesc">DITA-OT 3.3 includes <span class="ph" id="migrating-to-3.3__summary">new attribute sets for HTML5 customization, support for custom
integration processing, rotated table cells in PDF output, and hazard statements in HTML output</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.3 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.3/release-notes/" target="_blank" rel="external noopener">DITA-OT 3.3 Release Notes</a>.</div>
</section>
<section class="section"><h2 class="title sectiontitle">Secure connections to the plug-in registry</h2>
<div class="note attention note_attention"><span class="note__title">Attention:</span> To ensure data integrity during the plug-in installation process, Transport Layer Security
(TLS) will soon be required to access the plug-in registry. If you are using DITA-OT 3.3, 3.2, or 3.2.1 and are
unable to upgrade to the latest version, modify the <code class="ph codeph">registry</code> key in the
<span class="ph filepath">config/configuration.properties</span> file to switch the URI schema to
<code class="ph codeph">http<strong class="ph b">s</strong>://</code>, so the entry reads <code class="ph codeph">https://plugins.dita-ot.org/</code>.</div>
<p class="p">For more information, see
<a class="xref" href="plugins-registry.html" title="DITA-OT 3.2 supports a new plug-in registry that makes it easier to discover and install new plug-ins. The registry provides a searchable list of plug-ins at dita-ot.org/plugins.">Adding plug-ins via the registry</a>.</p>
</section>
<section class="section"><h2 class="title sectiontitle">Base plug-in files moved to <span class="ph filepath">plugins</span> directory</h2>
<p class="p">Various XSLT files and other resources have been moved from the root of the DITA-OT installation directory to
the base plug-in directory <span class="ph filepath">plugins/org.dita.base</span>.</p>
<div class="note attention note_attention"><span class="note__title">Attention:</span> There is no longer an <span class="ph filepath">xsl/</span> directory in the installation root.</div>
<p class="p">If your plug-ins use the <code class="ph codeph">plugin</code> URI scheme as recommended in the
<a class="xref" href="plugin-coding-conventions.html" title="To ensure custom plug-ins work well with the core toolkit code and remain compatible with future releases, the DITA Open Toolkit project recommends that plug-ins use modern development practices and common coding patterns.">Plug-in coding conventions</a>, this change should not require any modifications to custom plug-in
code:</p>
<blockquote class="lq">
<p class="p">In XSLT, use the <code class="ph codeph">plugin</code> URI scheme in <code class="keyword markupname xmlelement">&lt;xsl:import&gt;</code> and
<code class="keyword markupname xmlelement">&lt;xsl:include&gt;</code> to reference files in other plug-ins.</p>
<p class="p">Instead of:</p>
<div class="p"><pre class="pre codeblock language-xml"><code>&lt;xsl:import href="../../org.dita.base/xsl/common/output-message.xsl"/&gt;</code></pre></div>
<p class="p">use:</p>
<div class="p"><pre class="pre codeblock language-xml"><code>&lt;xsl:import href="plugin:org.dita.base:xsl/common/output-message.xsl"/&gt;</code></pre></div>
<p class="p">As with the plug-in directory property in Ant, this allows plug-ins to resolve to the correct directory even
when a plug-in moves to a new location. The plug-in is referenced using the syntax
<code class="ph codeph">plugin:<var class="keyword varname">plugin-id</var>:<var class="keyword varname">path/within/plugin/file.xsl</var></code>.</p>
</blockquote>
</section>
<section class="section"><h2 class="title sectiontitle">Relocated catalog</h2>
<p class="p">
<span class="ph" id="migrating-to-3.3__catalog">Along with the other base plug-in files, the <span class="ph filepath">catalog-dita.xml</span> file has
been moved from the root of the DITA-OT installation directory to <span class="ph filepath">plugins/org.dita.base</span>.
External systems that rely on this catalog should be updated with the new location. Ant scripts and DITA-OT
plug-ins should use the plug-in directory property to refer to the file as
<code class="ph codeph">${dita.plugin.org.dita.base.dir}/catalog-dita.xml</code>. A placeholder with a
<code class="keyword markupname xmlelement">&lt;nextCatalog&gt;</code> entry is provided in the original location for backwards compatibility,
but this file may be removed in an upcoming release.</span></p>
<figure class="fig fignone"><figcaption><span class="fig--title-label">Figure 1. </span>Legacy catalog placeholder content</figcaption>
<pre class="pre codeblock language-xml"><code>&lt;nextCatalog catalog="plugins/org.dita.base/catalog-dita.xml"/&gt;</code></pre>
</figure>
</section>
<section class="section"><h2 class="title sectiontitle">Deprecated properties</h2>
<p class="p"><span class="ph" id="migrating-to-3.3__templates">The <code class="ph codeph">templates</code> key in configuration properties has been deprecated in favor
of the <code class="keyword markupname xmlelement">&lt;template&gt;</code> element in <span class="ph filepath">plugin.xml</span>.</span></p>
</section>
<section class="section"><h2 class="title sectiontitle">New attribute sets for HTML5 customization</h2>
<div class="p" id="migrating-to-3.3__html5-att-sets">A series of new attribute sets has been added to the default HTML5 transformation to
facilitate customization with additional ARIA roles, attributes, or CSS classes. Attribute sets are provided
for:
<ul class="ul">
<li class="li"><code class="ph codeph">article</code></li>
<li class="li"><code class="ph codeph">banner</code></li>
<li class="li"><code class="ph codeph">footer</code></li>
<li class="li"><code class="ph codeph">main</code></li>
<li class="li"><code class="ph codeph">navigation</code></li>
<li class="li"><code class="ph codeph">toc</code></li>
</ul>If you have previously copied XSL templates (or template modes) to custom plug-ins only to add classes
required by web frameworks such as Bootstrap or Foundation (or your company CSS), you may be able to simplify
your customizations by using the new attribute sets instead of overriding the default templates.</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>

82
dita-ot-3.6/doc/topics/migrating-to-3.4.html Normal file
View file

@ -0,0 +1,82 @@
<!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.4 includes 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."><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.4</title></head><body id="migrating-to-3.4"><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 class="active"><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 to release 3.4</h1>
<div class="body refbody"><p class="shortdesc">DITA-OT 3.4 includes <span class="ph" id="migrating-to-3.4__summary">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>.</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.4 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.4/release-notes/" target="_blank" rel="external noopener">DITA-OT 3.4 Release Notes</a>.</div>
</section>
<section class="section"><h2 class="title sectiontitle">New indexing plug-in</h2>
<div class="sectiondiv" id="migrating-to-3.4__indexing-plugin">
<p class="p">DITA-OT 3.4 extracts the PDF indexing code to a separate <span class="ph filepath">org.dita.index</span> plug-in, and
adds a new <code class="ph codeph">depend.org.dita.pdf2.index</code> extension point that can be used to add custom index
processing targets to PDF output.</p>
<p class="p">The built-in index processing has been disabled and deprecated. If you have overridden index processing via
the <code class="ph codeph">transform.topic2fo</code> target in the past, you can set the new
<span class="keyword parmname">org.dita.index.skip</span> property to <span class="keyword option">yes</span> and re-enable the
<code class="ph codeph">transform.topic2fo.index</code> target with <code class="keyword markupname xmlelement">&lt;feature
extension="depend.org.dita.pdf2.index" value="transform.topic2fo.index"/&gt;</code> in your plug-in
configuration.</p>
</div>
<table class="table table-hover frame-none"><caption><span class="table--title-label">Table 1. </span><span class="title">New 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.4__entry__1">Plug-in </th>
<th class="entry colsep-0 rowsep-1" id="migrating-to-3.4__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.4__entry__1">org.dita.index</td>
<td class="entry colsep-0 rowsep-1" headers="migrating-to-3.4__entry__2">
<a class="xref" href="https://github.com/dita-ot/org.dita.index" target="_blank" rel="external noopener">https://github.com/dita-ot/org.dita.index</a></td>
</tr>
</tbody></table>
</section>
<section class="section" id="migrating-to-3.4__34-legacy-plugin-removal"><h2 class="title sectiontitle">Legacy plug-ins removed</h2>
<p class="p">DITA-OT 3.4 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 2. </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.4__34-legacy-plugin-removal__entry__1">Plug-in </th>
<th class="entry colsep-0 rowsep-1" id="migrating-to-3.4__34-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.4__34-legacy-plugin-removal__entry__1">TocJS</td>
<td class="entry colsep-0 rowsep-1" headers="migrating-to-3.4__34-legacy-plugin-removal__entry__2">
<a class="xref" href="https://github.com/dita-ot/com.sophos.tocjs" target="_blank" rel="external noopener">https://github.com/dita-ot/com.sophos.tocjs</a></td>
</tr>
<tr class="row">
<td class="entry colsep-0 rowsep-1" headers="migrating-to-3.4__34-legacy-plugin-removal__entry__1">troff</td>
<td class="entry colsep-0 rowsep-1" headers="migrating-to-3.4__34-legacy-plugin-removal__entry__2">
<a class="xref" href="https://github.com/dita-ot/org.dita.troff" target="_blank" rel="external noopener">https://github.com/dita-ot/org.dita.troff</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 plug-in(s) from the plug-in registry at
<a class="xref" href="https://www.dita-ot.org/plugins" target="_blank" rel="external noopener">dita-ot.org/plugins</a>, run the following command(s):</p>
<pre class="pre codeblock syntax-bash"><code><span class="keyword cmdname">dita</span> <span class="keyword parmname">--install</span>=<span class="ph filepath">com.sophos.tocjs</span>
<span class="keyword cmdname">dita</span> <span class="keyword parmname">--install</span>=<span class="ph filepath">org.dita.troff</span></code></pre>
</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>

170
dita-ot-3.6/doc/topics/migrating-to-3.5.html Normal file
View file

@ -0,0 +1,170 @@
<!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.5 includes support for additional input resources, an alternative subcommand syntax for the dita command, and an initial preview of features for the latest draft of the upcoming DITA 2.0 standard."><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.5</title></head><body id="migrating-to-3.5"><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 class="active"><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 to release 3.5</h1>
<div class="body refbody"><p class="shortdesc">DITA-OT 3.5 includes <span class="ph" id="migrating-to-3.5__summary">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>.</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.5 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.5/release-notes/" target="_blank" rel="external noopener">DITA-OT 3.5 Release Notes</a>.</div>
</section>
<section class="section" id="migrating-to-3.5__subcommands"><h2 class="title sectiontitle">New subcommands</h2>
<p class="p">The <span class="keyword cmdname">dita</span> command line interface has been refactored to support subcommands for common
operations.</p>
<div class="note important note_important"><span class="note__title">Important:</span> The new subcommands supersede the deprecated X-Toolkit–style single-hyphen keyword variants
(such as <span class="keyword option">-install</span>), and the corresponding GNU-style option keywords preceded by two hyphens
(such as <span class="keyword option">--install</span>).</div>
<dl class="dl">
<dt class="dt dlterm"><span class="keyword cmdname">dita install</span></dt>
<dd class="dd">Installs or reloads plug-ins (replaces <span class="keyword cmdname">dita</span>
<span class="keyword parmname">--install</span>)</dd>
<dt class="dt dlterm"><span class="keyword cmdname">dita plugins</span></dt>
<dd class="dd">Prints a list of installed plug-ins (replaces <span class="keyword cmdname">dita</span>
<span class="keyword parmname">--plugins</span>)</dd>
<dt class="dt dlterm"><span class="keyword cmdname">dita transtypes</span></dt>
<dd class="dd">Prints a list of installed transformation types, or <em class="ph i">output formats</em> (replaces
<span class="keyword cmdname">dita</span>
<span class="keyword parmname">--transtypes</span>)</dd>
<dt class="dt dlterm"><span class="keyword cmdname">dita uninstall</span></dt>
<dd class="dd">Removes and deletes a plug-in (replaces <span class="keyword cmdname">dita</span>
<span class="keyword parmname">--uninstall</span>)</dd>
<dt class="dt dlterm"><span class="keyword cmdname">dita version</span></dt>
<dd class="dd">Prints version information and exits (replaces <span class="keyword cmdname">dita</span>
<span class="keyword parmname">--version</span>)</dd>
</dl>
<div class="note tip note_tip"><span class="note__title">Tip:</span> The double-hyphen option syntax has been retained for backwards compatibility, so if you use
commands like <span class="keyword cmdname">dita</span>
<span class="keyword parmname">--install</span> in scripts, they will still work, but you may want to migrate your scripts to the
new subcommand syntax.</div>
</section>
<section class="section" id="migrating-to-3.5__3.5-legacy-target-removal"><h2 class="title sectiontitle">Legacy constructs removed</h2>
<p class="p">DITA-OT 3.5 no longer includes the following legacy properties, list files, and targets, which were deprecated
in previous releases. These constructs were no longer used in recent releases, and have now been removed
entirely.</p>
<p class="p">The following Ant targets have been removed from the pre-processing pipeline:</p>
<ul class="ul">
<li class="li"><code class="ph codeph">mappull</code> and <code class="ph codeph">mappull-check</code>, which were used to pull metadata (such as
navtitle) into the map from referenced topics prior to DITA-OT 2.2 (merged with
<code class="ph codeph">move-meta-entries</code>)</li>
<li class="li"><code class="ph codeph">conref-check</code>, deprecated since 2.3</li>
<li class="li"><code class="ph codeph">coderef</code>, which was used to resolve code references in input files prior to 2.3 (merged with
<code class="ph codeph">topic-fragment</code>)</li>
<li class="li"><code class="ph codeph">copy-subsidiary</code> and <code class="ph codeph">copy-subsidiary-check</code>, which were used to copy files
to the temporary directory prior to 2.1</li>
</ul>
<p class="p">Recent DITA-OT versions provide alternative mechanisms to achieve the same results, such as the
<code class="keyword markupname xmlelement">&lt;ditafileset&gt;</code> element to select resources in the temporary directory.</p>
<p class="p">Along with the obsolete targets, the following Ant properties have been removed:</p>
<ul class="ul">
<li class="li"><code class="ph codeph">canditopicsfile</code></li>
<li class="li"><code class="ph codeph">canditopicslist</code></li>
<li class="li"><code class="ph codeph">conreffile</code></li>
<li class="li"><code class="ph codeph">conreflist</code></li>
<li class="li"><code class="ph codeph">conreftargetsfile</code></li>
<li class="li"><code class="ph codeph">conreftargetslist</code></li>
<li class="li"><code class="ph codeph">copytosourcefile</code></li>
<li class="li"><code class="ph codeph">copytosourcelist</code></li>
<li class="li"><code class="ph codeph">fullditamapandtopicfile</code></li>
<li class="li"><code class="ph codeph">fullditamapandtopiclist</code></li>
<li class="li"><code class="ph codeph">fullditamapfile</code></li>
<li class="li"><code class="ph codeph">fullditamaplist</code></li>
<li class="li"><code class="ph codeph">fullditatopicfile</code></li>
<li class="li"><code class="ph codeph">fullditatopiclist</code></li>
<li class="li"><code class="ph codeph">hrefditatopicfile</code></li>
<li class="li"><code class="ph codeph">hrefditatopiclist</code></li>
<li class="li"><code class="ph codeph">hreftargetsfile</code></li>
<li class="li"><code class="ph codeph">hreftargetslist</code></li>
<li class="li"><code class="ph codeph">htmlfile</code></li>
<li class="li"><code class="ph codeph">htmllist</code></li>
<li class="li"><code class="ph codeph">imagefile</code></li>
<li class="li"><code class="ph codeph">imagelist</code></li>
<li class="li"><code class="ph codeph">outditafilesfile</code></li>
<li class="li"><code class="ph codeph">outditafileslist</code></li>
<li class="li"><code class="ph codeph">resourceonlyfile</code></li>
<li class="li"><code class="ph codeph">resourceonlylist</code></li>
<li class="li"><code class="ph codeph">subjectschemefile</code></li>
<li class="li"><code class="ph codeph">subjectschemelist</code></li>
<li class="li"><code class="ph codeph">subtargetsfile</code></li>
<li class="li"><code class="ph codeph">subtargetslist</code></li>
<li class="li"><code class="ph codeph">user.input.file.listfile</code></li>
<li class="li"><code class="ph codeph">user.input.file</code></li>
</ul>
<p class="p">The following obsolete list files are no longer generated in the temporary directory:</p>
<ul class="ul">
<li class="li"><span class="ph filepath">canditopics.list</span></li>
<li class="li"><span class="ph filepath">conref.list</span></li>
<li class="li"><span class="ph filepath">conreftargets.list</span></li>
<li class="li"><span class="ph filepath">copytosource.list</span></li>
<li class="li"><span class="ph filepath">fullditamap.list</span></li>
<li class="li"><span class="ph filepath">fullditamapandtopic.list</span></li>
<li class="li"><span class="ph filepath">fullditatopic.list</span></li>
<li class="li"><span class="ph filepath">hrefditatopic.list</span></li>
<li class="li"><span class="ph filepath">hreftargets.list</span></li>
<li class="li"><span class="ph filepath">html.list</span></li>
<li class="li"><span class="ph filepath">image.list</span></li>
<li class="li"><span class="ph filepath">outditafiles.list</span></li>
<li class="li"><span class="ph filepath">resourceonly.list</span></li>
<li class="li"><span class="ph filepath">subjectscheme.list</span></li>
<li class="li"><span class="ph filepath">subtargets.list</span></li>
<li class="li"><span class="ph filepath">user.input.file.list</span></li>
<li class="li"><span class="ph filepath">usr.input.file.list</span></li>
</ul>
<p class="p">For example, if your plug-in previously used the <code class="ph codeph">fullditatopicfile</code> to select resources in the
temporary directory like this:</p>
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;xslt basedir="${dita.temp.dir}"
destdir="${output.dir}"
includesfile="${dita.temp.dir}${file.separator}${fullditatopicfile}"
style="${args.xsl}"&gt;
&lt;!-- ⋮ --&gt;
&lt;/xslt&gt;</code></pre>
<p class="p"> With DITA-OT 2.4 or newer, use the <code class="keyword markupname xmlelement">&lt;ditafileset&gt;</code> element instead: </p>
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;xslt basedir="${dita.temp.dir}"
destdir="${output.dir}"
style="${args.xsl}"&gt;
&lt;ditafileset format="dita" processingRole="normal"/&gt;
&lt;!-- ⋮ --&gt;
&lt;/xslt&gt;</code></pre>
<p class="p">If your plug-in previously used the <code class="ph codeph">user.input.file.listfile</code> to process the start map like
this:</p>
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;xslt …
includesfile="${dita.temp.dir}${file.separator}${user.input.file.listfile}"/&gt;</code></pre>
<p class="p">Use the <code class="keyword markupname xmlelement">&lt;ditafileset&gt;</code> element as follows:</p>
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;xslt … &gt;
&lt;ditafileset input="true" format="ditamap"/&gt;
&lt;/xslt&gt;</code></pre>
</section>
<section class="section" id="migrating-to-3.5__rewriting-output-files"><h2 class="title sectiontitle">Adjusting output file names</h2>
<p class="p">Two new parameters can be used to dynamically adjust the names and locations of output files in transformations
that use the map-first pre-processing routine (<code class="ph codeph">preprocess2</code>).</p>
<div class="p">These parameters can be passed on the command line, or included in a custom plug-in via
<code class="keyword markupname xmlelement">&lt;property&gt;</code> elements in an Ant script as described in
<a class="xref" href="plugin-rewrite-rules.html" title="To dynamically adjust the names and locations of output files in the map-first pre-processing routine (preprocess2), you can create a custom plug-in and specify the code that contains your custom rewrite rules.">Adjusting file names in map-first pre-processing</a>.
<ul class="ul">
<li class="li">Use <span class="keyword parmname">result.rewrite-rule.class</span> to rewrite filenames with a Java class that implements
the <code class="ph codeph">org.dita.dost.module.RewriteRule</code> interface</li>
<li class="li">Use <span class="keyword parmname">result.rewrite-rule.xsl</span> to rewrite via an XSLT stylesheet</li>
</ul>
</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>

108
dita-ot-3.6/doc/topics/migrating-to-3.6.html Normal file
View file

@ -0,0 +1,108 @@
<!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.6 includes 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 audio and video elements, and the new emphasis domain."><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.6</title></head><body id="migrating-to-3.6"><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 class="active"><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 to release 3.6</h1>
<div class="body refbody"><p class="shortdesc">DITA-OT 3.6 includes <span class="ph" id="migrating-to-3.6__summary">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">&lt;audio&gt;</code>
and <code class="keyword markupname xmlelement">&lt;video&gt;</code> elements, and the new emphasis domain</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.6 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.6/release-notes/" target="_blank" rel="external noopener">DITA-OT 3.6 Release Notes</a>.</div>
</section>
<section class="section" id="migrating-to-3.6__parallel-processing"><h2 class="title sectiontitle">Parallel processing</h2>
<p class="p">Preprocessing module code can now be run in parallel by setting the <span class="keyword parmname">parallel</span> parameter to
<span class="keyword option">true</span>. The performance benefits this option provides depend heavily on the source file set,
the DITA features used in the project, and the computer doing the processing, but under the right circumstances,
you may see notable improvements when this option is enabled.</p>
</section>
<section class="section" id="migrating-to-3.6__in-memory-processing"><h2 class="title sectiontitle">In-memory processing</h2>
<p class="p">DITA-OT 3.6 introduces a new Store API with preview support for in-memory processing. The Cache Store can be
activated by setting the <span class="keyword parmname">store-type</span> parameter to <span class="keyword option">memory</span>.
<span class="ph" id="migrating-to-3.6__io-bound">In-memory processing provides performance advantages in I/O bound environments such as cloud
computing platforms, where processing time depends primarily on how long it takes to read and write temporary
files.</span> For more information, see
<a class="xref" href="../reference/store-api.html" title="DITA-OT originally assumed resources would be available on disk and available from file paths. Recent versions added URI input, so HTTPS resources could be used, but temporary and output resources were still file-based. DITA-OT 3.6 introduces a new Store API that can process temporary resources in memory instead of writing them to disk.">Store API – Processing in memory</a>.</p>
</section>
<section class="section"><h2 class="title sectiontitle">Caching DITA class instances</h2>
<p class="p">The DITA-OT Java code uses a new caching <code class="ph codeph">DitaClass.getInstance(cls)</code> factory method rather than
generating <code class="ph codeph">DitaClass</code> instances directly. This allows previously created instances to be
re-used, which reduces the number of instances that need to be created.</p>
<div class="note important note_important"><span class="note__title">Important:</span> Custom plug-ins that use the <code class="ph codeph">DitaClass</code> constructor in Java code should be
updated to use the <code class="ph codeph">getInstance</code> factory method instead.</div>
</section>
<section class="section" id="migrating-to-3.6__fop-changebars"><h2 class="title sectiontitle">PDF changebars with Apache FOP</h2>
<p class="p">For DITA-OT 3.4, the bundled Apache™ Formatting Objects Processor library was upgraded to version 2.4, which
included support for changebars, but those features were not yet enabled in DITA-OT 3.4 pending further testing.
DITA-OT 3.6 removes the FOP-specific overrides that disabled changebars in earlier versions, allowing the
default PDF2 flagging routines to be applied when generating PDFs with FOP. For details, see
<a class="xref" href="pdf2-creating-change-bars.html" title="You can generate revision bars in your PDF output by using the changebar and color attributes of the DITAVAL revprop element.">Generating revision bars</a>.</p>
<p class="p">Plug-ins that implemented custom FOP flagging by overriding the
<span class="ph filepath">org.dita.pdf2.fop/xsl/fo/flagging_fop.xsl</span> stylesheet in prior versions will need to be
updated, as this file is no longer available in DITA-OT 3.6.
<a class="xref" href="https://github.com/dita-ot/dita-ot/issues/3511" target="_blank" rel="external noopener">#3511</a>,
<a class="xref" href="https://github.com/dita-ot/dita-ot/issues/3591" target="_blank" rel="external noopener">#3591</a>
</p>
</section>
<section class="section" id="migrating-to-3.6__no-dublin-core"><h2 class="title sectiontitle">Dublin Core metadata removed from HTML5</h2>
<p class="p">Up to version 3.5, DITA-OT included the
<a class="xref" href="https://dublincore.org/specifications/dublin-core/dcmi-terms" target="_blank" rel="external noopener">Dublin Core Metadata Element Set</a> in both XHTML and HTML5 output. DITA-OT 3.6 no longer generates Dublin Core
metadata in HTML5 output.</p>
<div class="note tip note_tip"><span class="note__title">Tip:</span> If necessary, the
<a class="xref" href="https://github.com/dita-ot/org.dita.html5.dublin-core/" target="_blank" rel="external noopener">org.dita.html5.dublin-core</a> plug-in can be installed from the plug-in registry at
<a class="xref" href="https://www.dita-ot.org/plugins" target="_blank" rel="external noopener">dita-ot.org/plugins</a> to add Dublin Core metadata to HTML5.</div>
<p class="p">To install the plug-in, run the following command:</p>
<pre class="pre codeblock syntax-bash"><code><span class="keyword cmdname">dita install</span> org.dita.html5.dublin-core</code></pre>
</section>
<section class="section" id="migrating-to-3.6__3.6-inline-styles"><h2 class="title sectiontitle">Legacy style attributes moved to CSS</h2>
<div class="p">Remaining inline style attributes were removed from HTML5 code, which prevented custom plug-ins from overriding
the presentation of the corresponding elements, including:
<ul class="ul">
<li class="li"><span class="ph line-through"><code class="keyword markupname xmlelement">&lt;line-through&gt;</code></span> and
<span class="ph overline"><code class="keyword markupname xmlelement">&lt;overline&gt;</code></span> elements</li>
<li class="li">syntax diagrams</li>
<li class="li">long quote citations</li>
<li class="li">Boolean states</li>
</ul></div>
<p class="p">These changes move the default presentation rules to CSS to allow users to override these styles in custom
stylesheets. The output is visually equivalent to the results generated by previous toolkit versions. </p>
<div class="note important note_important"><span class="note__title">Important:</span> In publishing environments that do not use the default common CSS files, these styles may
need to be implemented in custom stylesheets.</div>
</section>
<section class="section" id="migrating-to-3.6__no-msgprefix"><h2 class="title sectiontitle">XSL variable <code class="ph codeph">msgprefix</code> removed</h2>
<p class="p">The <code class="ph codeph">msgprefix</code> variable (“DOTX”) has been deprecated since DITA-OT 2.3 and is now removed from
DITA-OT 3.6. For more information, see
<a class="xref" href="migrating-to-2.3.html" title="In DITA-OT 2.3, HTML5 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 id variable that contains the entire message ID.">Migrating to release 2.3</a>.</p>
</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>

34
dita-ot-3.6/doc/topics/migration.html Normal file
View file

File diff suppressed because one or more lines are too long

42
dita-ot-3.6/doc/topics/other-errors.html Normal file
View file

@ -0,0 +1,42 @@
<!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="In addition to error messages that DITA Open Toolkit generates, you might also encounter error messages generated by Java or other tools."><meta name="keywords" content="logging, Java, out of memory, UnsupportedClassVersionError, tools.jar, XSLT, errors, preprocessing, XSLT, debugging, generate-debug-attributes, memory"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Other error messages</title></head><body id="troubleshooting"><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></li><li><a href="../topics/troubleshooting-overview.html">Troubleshooting</a><ul><li><a href="../topics/logging.html">Logging</a></li><li><a href="../topics/enabling-debug-mode.html">Enabling debug mode</a></li><li><a href="../topics/error-messages.html">DITA-OT error messages</a></li><li class="active"><a href="../topics/other-errors.html">Other error messages</a></li><li><a href="../topics/dita-command-help.html">Command line help</a></li><li><a href="../topics/increasing-the-jvm.html">Increasing Java memory</a></li><li><a href="../topics/reducing-processing-time.html">Speeding up builds</a></li></ul></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">Other error messages</h1>
<div class="body refbody"><p class="shortdesc">In addition to error messages that DITA Open Toolkit generates, you might also encounter error messages
generated by Java or other tools.</p>
<section class="section" id="troubleshooting__out-of-memory-error"><h2 class="title sectiontitle">Out of Memory error</h2>
<p class="p">In some cases, you might receive a message stating the build has failed due to an <samp class="ph msgph">Out of Memory</samp>
error. Try the following approaches to resolve the problem:</p>
<ol class="ol">
<li class="li">Increase the memory available to Java.</li>
<li class="li">Reduce memory consumption by setting the <span class="keyword option">generate-debug-attributes</span> option to
<code class="ph codeph">false</code>. This option is set in the <span class="ph filepath">lib/configuration.properties</span> file.
This will disable debug attribute generation (used to trace DITA-OT error messages back to source files) and
will reduce memory consumption.</li>
<li class="li">Set <code class="ph codeph">dita.preprocess.reloadstylesheet</code> Ant property to <code class="ph codeph">true</code>. This will allow
the XSLT processor to release memory when converting multiple files.</li>
<li class="li">Run the transformation again.</li>
</ol>
</section>
<section class="section" id="troubleshooting__unsupported-class-version-error"><h2 class="title sectiontitle">UnsupportedClassVersionError</h2>
<p class="p">If you receive a <code class="ph codeph">java.lang.UnsupportedClassVersionError</code> error message with an
<code class="ph codeph">Unsupported major.minor version</code> and a list of Java classes, make sure your system meets the
minimum Java requirements as listed in the <cite class="cite">Release Notes</cite> and installation instructions.</p>
</section>
<section class="section" id="troubleshooting__tools-jar-error"><h2 class="title sectiontitle">Unable to locate tools.jar</h2>
<p class="p">If a Java Runtime Environment (JRE) is used when building output via Ant, the <samp class="ph msgph">Unable to locate
tools.jar</samp> error may appear. This message is safe to ignore, since DITA-OT does not rely on any of the
functions in this library. If a Java Development Kit (JDK) is also installed, setting the
<var class="keyword varname">JAVA_HOME</var> environment variable to the location of the JDK will prevent this message from
appearing.</p>
</section>
</div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/troubleshooting-overview.html" title="This section contains information about problems that you might encounter and how to resolve them.">Error messages and troubleshooting</a></div></div><div class="linklist reltasks"><strong>Related tasks</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/increasing-the-jvm.html" title="If you are working with large documents with extensive metadata or key references, you will need to increase the memory allocation for the Java process. You can do this from the command-line prompt for a specific session, or you can increase the value of the ANT_OPTS environment variable.">Increasing Java memory allocation</a></li><li class="linklist"><a class="link" href="../topics/installing-client.html" title="The DITA-OT distribution package can be installed on Linux, macOS, and Windows. It contains everything that you need to run the toolkit except for Java.">Installing DITA Open Toolkit</a></li></ul></div><div class="linklist relref"><strong>Related reference</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../parameters/parameters-other.html" title="These parameters enable you to reload style sheets that DITA-OT uses for specific pre-processing stages.">Other parameters</a></li><li class="linklist"><a class="link" href="../release-notes/index.html" title="DITA Open Toolkit 3.6 includes 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 audio and video elements, and the new emphasis domain.">DITA Open Toolkit 3.6 Release Notes</a></li></ul></div></nav></article></main></body></html>

17
dita-ot-3.6/doc/topics/output-formats.html Normal file
View file

@ -0,0 +1,17 @@
<!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 Open Toolkit ships with several core transformations that convert DITA content to different output formats. Additional formats are available from the plug-in registry at dita-ot.org/plugins."><meta name="keywords" content="output formats, transformations, DITA specification, plug-ins, default, list of"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>DITA-OT transformations (output formats)</title></head><body id="availabletransforms"><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 class="active"><a href="../topics/output-formats.html">Output formats</a><ul><li><a href="../topics/dita2pdf.html">PDF</a></li><li><a href="../topics/dita2html5.html">HTML5</a></li><li><a href="../topics/dita2eclipsehelp.html">Eclipse help</a></li><li><a href="../topics/dita2htmlhelp.html">HTML Help</a></li><li><a href="../topics/dita2markdown.html">Markdown</a></li><li><a href="../topics/dita2dita.html">Normalized DITA</a></li><li><a href="../topics/dita2xhtml.html">XHTML</a></li></ul></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></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">DITA-OT transformations (output formats)</h1>
<div class="body conbody"><p class="shortdesc">DITA Open Toolkit ships with several core transformations that convert DITA content to different output
formats. Additional formats are available from the plug-in registry at
<a class="xref" href="https://www.dita-ot.org/plugins" target="_blank" rel="external noopener">dita-ot.org/plugins</a>.</p>
<div class="note tip note_tip"><span class="note__title">Tip:</span> For information on how to install other formats, see
<a class="xref" href="adding-plugins.html" title="You can extend DITA-OT with additional plug-ins to change the default output types in various ways, add entirely new kinds of output formats, or implement DITA specializations. A variety of open source plug-ins are available from the plug-in registry at dita-ot.org/plugins.">Adding and removing plug-ins</a>.</div>
</div>
<nav role="navigation" class="related-links"><ul class="ullinks"><li class="link ulchildlink"><strong><a href="../topics/dita2pdf.html">PDF</a></strong><br>The <span class="keyword option">pdf</span> transformation generates output in Portable Document Format.</li><li class="link ulchildlink"><strong><a href="../topics/dita2html5.html">HTML5</a></strong><br>The <span class="keyword option">html5</span> transformation generates HTML5 output and a table of contents (TOC) file.</li><li class="link ulchildlink"><strong><a href="../topics/dita2eclipsehelp.html">Eclipse help</a></strong><br>The <span class="keyword option">eclipsehelp</span> transformation generates XHTML output, CSS files, and the control files that are needed for Eclipse help.</li><li class="link ulchildlink"><strong><a href="../topics/dita2htmlhelp.html">HTML Help</a></strong><br>The <span class="keyword option">htmlhelp</span> transformation generates HTML output, CSS files, and the control files that are needed to produce a Microsoft Compiled HTML Help (.chm) file.</li><li class="link ulchildlink"><strong><a href="../topics/dita2markdown.html">Markdown</a></strong><br>Along with Markdown input, DITA-OT now provides three new transformation types to convert DITA content to Markdown, including the original syntax, GitHub-Flavored Markdown, and GitBook.</li><li class="link ulchildlink"><strong><a href="../topics/dita2dita.html">Normalized DITA</a></strong><br>The <code class="ph codeph">dita</code> transformation generates normalized topics and maps from DITA input. The normalized output includes the results of DITA Open Toolkit pre-processing operations, which resolve map references, keys, content references, code references and push metadata back and forth between maps and topics.</li><li class="link ulchildlink"><strong><a href="../topics/dita2xhtml.html">XHTML</a></strong><br>The <span class="keyword option">xhtml</span> transformation generates XHTML output and a table of contents (TOC) file. This was the first transformation created for DITA Open Toolkit, and originally served as the basis for all HTML-based transformations.</li></ul></nav></article></main></body></html>

85
dita-ot-3.6/doc/topics/pdf-customization-approaches.html Normal file
View file

@ -0,0 +1,85 @@
<!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="Various methods may be used to customize the PDF output that DITA Open Toolkit produces. Each of these approaches have advantages and shortcomings that should be considered when preparing a customization project."><meta name="keywords" content="PDF, customizing, best practices, upgrading, default plug-ins, PDF"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>PDF customization approaches</title></head><body id="pdf_customization_approaches"><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><ul><li class="active"><a href="../topics/pdf-customization-approaches.html">Customization approaches</a></li><li><a href="../topics/pdf2-creating-change-bars.html">Generating revision bars</a></li></ul></li><li><a href="../topics/adding-plugins.html">Adding plug-ins</a></li><li><a href="../topics/custom-plugins.html">Creating plug-ins</a></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">PDF customization approaches</h1>
<div class="body conbody"><p class="shortdesc">Various methods may be used to customize the PDF output that DITA Open Toolkit produces. Each of these
approaches have advantages and shortcomings that should be considered when preparing a customization
project.</p>
<div class="note note note_note"><span class="note__title">Note:</span> Some of these methods are considered “anti-patterns” with disadvantages that outweigh their apparent appeal.
In most cases, you should create a custom PDF plug-in.</div>
<section class="section" id="pdf_customization_approaches__why_not_edit_default_files"><h2 class="title sectiontitle">Why not edit default files?</h2>
<p class="p">When first experimenting with PDF customization, novice users are often tempted to simply edit the default
<span class="ph filepath">org.dita.pdf2</span> files in place to see what happens.</p>
<p class="p">As practical as this approach may seem, the DITA-OT project does not recommend changing any of the files in the
default plug-ins.</p>
<p class="p">While this method yields quick results and can help users to determine which files and templates control
various aspects of PDF output, it quickly leads to problems, as any errors may prevent the toolkit from
generating PDF output.</p>
<div class="note warning note_warning"><span class="note__title">Warning:</span> Any changes made in this fashion would be overwritten when upgrading to newer versions of
DITA-OT, so users that have customized their toolkit installation in this way are often “stuck” on older
versions of the toolkit and unable to take advantage of improvements in recent versions of DITA-OT.</div>
</section>
<section class="section" id="pdf_customization_approaches__the_customization_folder"><h2 class="title sectiontitle">Using the <span class="ph filepath">Customization</span> folder</h2>
<p class="p">The original Idiom plug-in used its own extension mechanism to provide overrides to the PDF transformation.
With this approach, a dedicated folder within the plug-in is used to store customized files.</p>
<p class="p">Files in the <span class="ph filepath">org.dita.pdf2/Customization</span> folder can override their default counterparts,
allowing users to adjust certain aspects of PDF output without changing any of the plug-in’s default files, or
specifying additional parameters when generating output.</p>
<div class="note important note_important"><span class="note__title">Important:</span> While this approach is slightly better than editing default files in place, it can still
cause problems when upgrading the toolkit to a new version. Since the <span class="ph filepath">Customization</span> folder
is located within the <span class="ph filepath">org.dita.pdf2</span> plug-in’s parent directory, users must be take care to
preserve the contents of this folder when upgrading to new toolkit versions.</div>
<p class="p">Although recent versions of DITA-OT still support this mechanism to ensure backwards compatibility, this
practice is deprecated in favor of custom PDF plug-ins.</p>
<div class="note tip note_tip"><span class="note__title">Tip:</span> Users who have used the <span class="ph filepath">Customization</span> folder to modify the default PDF
output are encouraged to create a custom PDF plug-in instead. In many cases, this may be as simple as copying
the contents of the <span class="ph filepath">Customization</span> folder to a new subfolder in the
<span class="ph filepath">plugins</span> folder and creating the necessary <span class="ph filepath">plugin.xml</span> file and an Ant
script to define the transformation type as described in the following example.</div>
</section>
<section class="section" id="pdf_customization_approaches__external_customization_directories"><h2 class="title sectiontitle">Specifying an external customization directory</h2>
<p class="p">To ensure that overrides in customization folders are not overwritten when upgrading DITA-OT to a new release,
an external customization directory can be specified at build time or in build scripts via the
<span class="keyword parmname">customization.dir</span> parameter.</p>
<p class="p">This method is preferable to the use of the <span class="ph filepath">org.dita.pdf2/Customization</span> folder, as the
contents of external folders are unaffected when upgrading DITA-OT. In distributed environments, users can use
local installations of DITA-OT, yet still take advantage of common customizations stored in a network location
available to the entire team, such as a shared drive.</p>
<p class="p">It can also be useful in environments where corporate policy, CMS permissions, or network access rights prevent
changes to the toolkit installation, which may prohibit the installation of custom plug-ins.</p>
<div class="note tip note_tip"><span class="note__title">Tip:</span> Users who specify external customization directories via <span class="keyword parmname">customization.dir</span>
are encouraged to create a custom PDF plug-in if possible.</div>
</section>
<section class="section" id="pdf_customization_approaches__plug_ins_and_customization_folders"><h2 class="title sectiontitle">Combining custom plug-ins &amp; customization directories</h2>
<p class="p">A common custom plug-in may be used to store base overrides that are applicable to all company publications,
and the <span class="keyword parmname">customization.dir</span> parameter can be passed at build time to override individual
settings as necessary for a given project or publication.</p>
<p class="p">In this case, any settings in the customization directory will take precedence over their counterparts in the
custom plug-in or default <span class="ph filepath">org.dita.pdf2</span> plug-in.</p>
<p class="p">This approach allows a single custom plug-in to be shared between multiple publications or the entire company,
without the need to create additional plug-in dependencies per project.</p>
<p class="p">However, the use of multiple customization mechanisms can make it difficult to debug the precedence cascade and
determine the origin of local formatting or processing overrides.</p>
<div class="note tip note_tip"><span class="note__title">Tip:</span> In most scenarios, the use of dedicated PDF customization plug-ins is preferable. Common
customizations can be bundled in one plug-in, and any project-specific overrides can be maintained in separate
plug-ins that build on the base branding or other settings in the common custom plug-in.</div>
</section>
</div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/pdf-customization.html" title="You can adjust various aspects of PDF output by changing parameter settings. For more complex customizations, you can create custom DITA-OT plug-ins.">Customizing PDF output</a></div></div><div class="linklist reltasks"><strong>Related tasks</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/pdf-customization-plugins.html" title="In most cases, PDF output should be customized by creating custom DITA-OT plug-ins that build on the default DITA to PDF transformation. PDF plug-ins can customize covers and page layouts, modify formatting, override the logic of the default PDF plug-in, and much more.">Custom PDF plug-ins</a></li></ul></div></nav></article></main></body></html>

157
dita-ot-3.6/doc/topics/pdf-customization-example.html Normal file
View file

@ -0,0 +1,157 @@
<!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="This scenario walks through the process of creating a very simple plug-in (com.example.print-pdf) that creates a new transformation type: print-pdf."><meta name="keywords" content=", figure, PDF, plug-in, integrator.xml, catalog, example"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Example: Creating a simple PDF plug-in</title></head><body id="dita2pdf-customization"><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><ul><li><a href="../topics/pdf-customization-plugin-types.html">Types of PDF plug-ins</a></li><li><a href="../topics/pdf-plugin-structure.html">PDF plug-in structure</a></li><li class="active"><a href="../topics/pdf-customization-example.html">Simple PDF plug-in</a></li><li><a href="../topics/pdf-customization-resources.html">PDF plug-in resources</a></li></ul></li><li><a href="../topics/globalization.html">Globalizing DITA content</a></li><li><a href="../topics/migration.html">Migrating customizations</a></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">Example: Creating a simple PDF plug-in</h1>
<div class="body taskbody"><p class="shortdesc">This scenario walks through the process of creating a very simple plug-in
(<code class="ph codeph">com.example.print-pdf</code>) that creates a new transformation type: <span class="keyword option">print-pdf</span>. </p>
<section class="section context"><div class="tasklabel"><h2 class="sectiontitle tasklabel">About this task</h2></div>
<p class="p">The <span class="keyword option">print-pdf</span> transformation has the following characteristics:</p>
<ul class="ul">
<li class="li">Uses A4 paper </li>
<li class="li">Renders figures with a title at the top and a description at the bottom</li>
<li class="li">Use em dashes as the symbols for unordered lists</li>
</ul>
</section>
<section><div class="tasklabel"><h2 class="sectiontitle tasklabel">Procedure</h2></div><ol class="ol steps"><li class="li step stepexpand">
<span class="ph cmd">In the <span class="ph filepath">plugins</span> directory, create a directory named
<span class="ph filepath">com.example.print-pdf</span>.</span>
</li><li class="li step stepexpand">
<span class="ph cmd">In the new <span class="ph filepath">com.example.print-pdf</span> directory, create a plug-in configuration file
(<span class="ph filepath">plugin.xml</span>) that declares the new <span class="keyword option">print-pdf</span> transformation and its
dependencies.</span>
<div class="itemgroup info">
<figure class="fig fignone"><figcaption><span class="fig--title-label">Figure 1. </span><span class="ph filepath">plugin.xml</span> file</figcaption>
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;?xml-model href="https://www.dita-ot.org/rng/plugin.rnc" type="application/relax-ng-compact-syntax"?&gt;
&lt;plugin id="com.example.print-pdf"&gt;
&lt;require plugin="org.dita.pdf2"/&gt;
&lt;transtype name="print-pdf" extends="pdf" desc="PDF on A4 paper"/&gt;
&lt;feature extension="dita.transtype.print" value="print-pdf"/&gt;
&lt;feature extension="ant.import" file="integrator.xml"/&gt;
&lt;/plugin&gt;</code></pre>
</figure>
</div>
</li><li class="li step stepexpand">
<span class="ph cmd">Add an Ant script (<span class="ph filepath">integrator.xml</span>) to define the transformation type.</span>
<div class="itemgroup info">
<figure class="fig fignone"><figcaption><span class="fig--title-label">Figure 2. </span><span class="ph filepath">integrator.xml</span> file</figcaption>
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;?xml version='1.0' encoding='UTF-8'?&gt;
&lt;project&gt;
&lt;target name="dita2print-pdf"
depends="dita2print-pdf.init,
dita2pdf2"/&gt;
&lt;target name="dita2print-pdf.init"&gt;
&lt;property name="customization.dir"
location="${dita.plugin.com.example.print-pdf.dir}/cfg"/&gt;
&lt;/target&gt;
&lt;/project&gt;</code></pre>
</figure></div>
</li><li class="li step stepexpand">
<span class="ph cmd">In the new plug-in directory, add a <span class="ph filepath">cfg/catalog.xml</span> file that specifies the custom
XSLT style sheets.</span>
<div class="itemgroup stepxmp">
<figure class="fig fignone"><figcaption><span class="fig--title-label">Figure 3. </span><span class="ph filepath">cfg/catalog.xml</span> file</figcaption>
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;catalog prefer="system"
xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"&gt;
&lt;uri name="cfg:fo/attrs/custom.xsl" uri="fo/attrs/custom.xsl"/&gt;
&lt;uri name="cfg:fo/xsl/custom.xsl" uri="fo/xsl/custom.xsl"/&gt;
&lt;/catalog&gt;</code></pre>
</figure>
</div>
</li><li class="li step stepexpand">
<span class="ph cmd">Create the <span class="ph filepath">cfg/fo/attrs/custom.xsl</span> file, and add attribute and variable overrides to
it.</span>
<div class="itemgroup stepxmp">For example, add the following variables to change the page size to A4.<figure class="fig fignone"><figcaption><span class="fig--title-label">Figure 4. </span><span class="ph filepath">cfg/fo/attrs/custom.xsl</span> file</figcaption>
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version="2.0"&gt;
&lt;!-- Change page size to A4 --&gt;
&lt;xsl:variable name="page-width"&gt;210mm&lt;/xsl:variable&gt;
&lt;xsl:variable name="page-height"&gt;297mm&lt;/xsl:variable&gt;
&lt;/xsl:stylesheet&gt;</code></pre>
</figure></div>
</li><li class="li step stepexpand">
<span class="ph cmd">Create the <span class="ph filepath">cfg/fo/xsl/custom.xsl</span> file, and add XSLT overrides to it.</span>
<div class="itemgroup stepxmp">For example, the following code changes the rendering of <code class="keyword markupname xmlelement">&lt;figure&gt;</code> elements.<figure class="fig fignone"><figcaption><span class="fig--title-label">Figure 5. </span><span class="ph filepath">cfg/fo/xsl/custom.xsl</span> file</figcaption>
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:fo="http://www.w3.org/1999/XSL/Format"
version="2.0"&gt;
&lt;!-- Move figure title to top and description to bottom --&gt;
&lt;xsl:template match="*[contains(@class,' topic/fig ')]"&gt;
&lt;fo:block xsl:use-attribute-sets="fig"&gt;
&lt;xsl:call-template name="commonattributes"/&gt;
&lt;xsl:if test="not(@id)"&gt;
&lt;xsl:attribute name="id"&gt;
&lt;xsl:call-template name="get-id"/&gt;
&lt;/xsl:attribute&gt;
&lt;/xsl:if&gt;
&lt;xsl:apply-templates select="*[contains(@class,' topic/title ')]"/&gt;
&lt;xsl:apply-templates select="*[not(contains(@class,' topic/title ') or contains(@class,' topic/desc '))]"/&gt;
&lt;xsl:apply-templates select="*[contains(@class,' topic/desc ')]"/&gt;
&lt;/fo:block&gt;
&lt;/xsl:template&gt;
&lt;/xsl:stylesheet&gt;</code></pre>
</figure></div>
</li><li class="li step stepexpand">
<span class="ph cmd">Create an English-language variable-definition file (<span class="ph filepath">cfg/common/vars/en.xml</span>) and make
any necessary modifications to it.</span>
<div class="itemgroup stepxmp">For example, the following code removes the period after the number for an ordered-list item; it also
specifies that the bullet for an unordered list item should be an em dash.<figure class="fig fignone"><figcaption><span class="fig--title-label">Figure 6. </span><span class="ph filepath">cfg/common/vars/en.xml</span> file</figcaption>
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;vars xmlns="http://www.idiominc.com/opentopic/vars"&gt;
&lt;!-- Remove dot from list number --&gt;
&lt;variable id="Ordered List Number"&gt;
&lt;param ref-name="number"/&gt;
&lt;/variable&gt;
&lt;!-- Change unordered list bullet to an em dash --&gt;
&lt;variable id="Unordered List bullet"&gt;&amp;#x2014;&lt;/variable&gt;
&lt;/vars&gt;</code></pre>
</figure></div>
</li></ol></section>
<section class="section result"><div class="tasklabel"><h2 class="sectiontitle tasklabel">Results</h2></div>
<div class="note tip note_tip"><span class="note__title">Tip:</span> The files for this sample plug-in are included in the DITA-OT installation directory under
<span class="ph filepath">docsrc/samples/plugins/com.example.print-pdf/</span> and on
<a class="xref" href="https://github.com/dita-ot/docs/tree/develop/samples/plugins/com.example.print-pdf" target="_blank" rel="external noopener">GitHub</a>.</div>
<p class="p">The plug-in directory has the following layout and files:</p>
<pre class="pre codeblock"><code>com.example.print-pdf
├── cfg
│&nbsp;&nbsp; ├── catalog.xml
│&nbsp;&nbsp; ├── common
│&nbsp;&nbsp; │&nbsp;&nbsp; └── vars
│&nbsp;&nbsp; │&nbsp;&nbsp; └── en.xml
│&nbsp;&nbsp; └── fo
│&nbsp;&nbsp; ├── attrs
│&nbsp;&nbsp; │&nbsp;&nbsp; └── custom.xsl
│&nbsp;&nbsp; └── xsl
│&nbsp;&nbsp; └── custom.xsl
├── integrator.xml
└── plugin.xml</code></pre>
</section>
<section class="section postreq"><div class="tasklabel"><h2 class="sectiontitle tasklabel">What to do next</h2></div>
<ol class="ol">
<li class="li">Run <span class="ph filepath"><span class="keyword cmdname">dita</span></span>
<span class="keyword parmname">--install</span> to install the plug-in and make the <span class="keyword option">print-pdf</span> transformation
available.</li>
<li class="li">Build output with the new transformation type to verify that the plug-in works as intended.
<pre class="pre codeblock"><code><span class="ph filepath"><span class="keyword cmdname">dita</span></span> <span class="keyword parmname">--input</span>=<var class="keyword varname">my.ditamap</var> <span class="keyword parmname">--format</span>=<span class="keyword option">print-pdf</span></code></pre>
</li>
</ol>
</section>
</div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/pdf-customization-plugins.html" title="In most cases, PDF output should be customized by creating custom DITA-OT plug-ins that build on the default DITA to PDF transformation. PDF plug-ins can customize covers and page layouts, modify formatting, override the logic of the default PDF plug-in, and much more.">Custom PDF plug-ins</a></div></div><div class="linklist reltasks"><strong>Related tasks</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/plugins-installing.html" title="Use the dita install subcommand to install plug-ins.">Installing plug-ins</a></li></ul></div></nav></article></main></body></html>

32
dita-ot-3.6/doc/topics/pdf-customization-plugin-types.html Normal file
View file

@ -0,0 +1,32 @@
<!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="There are two common types of plug-ins: A plug-in that simply sets the DITA-OT parameters to be used when a PDF is generated, and a plug-in that overrides aspects of the base DITA-OT PDF transformation. A plug-in can, of course, do both of these things."><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Types of custom PDF plug-ins</title></head><body id="types-pdf-customization-plugins"><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><ul><li class="active"><a href="../topics/pdf-customization-plugin-types.html">Types of PDF plug-ins</a></li><li><a href="../topics/pdf-plugin-structure.html">PDF plug-in structure</a></li><li><a href="../topics/pdf-customization-example.html">Simple PDF plug-in</a></li><li><a href="../topics/pdf-customization-resources.html">PDF plug-in resources</a></li></ul></li><li><a href="../topics/globalization.html">Globalizing DITA content</a></li><li><a href="../topics/migration.html">Migrating customizations</a></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">Types of custom PDF plug-ins</h1>
<div class="body conbody"><p class="shortdesc">There are two common types of plug-ins: A plug-in that simply sets the DITA-OT parameters to be used when a
PDF is generated, and a plug-in that overrides aspects of the base DITA-OT PDF transformation. A plug-in can, of
course, do both of these things.</p>
<section class="section"><h2 class="title sectiontitle">Plug-in that only provides DITA-OT parameters</h2>
<p class="p">You might want to build a transformation type that uses a transformation as-is; however, you might want to
ensure that certain DITA-OT parameters are used. For an example of this approach, see
<a class="xref" href="plugin-set-parameters.html" title="To ensure that output is always generated with the same settings, you can create a plug-in to define a new output format that automatically sets certain DITA-OT parameters.">Setting parameters with plug-ins</a>.</p>
</section>
<section class="section"><h2 class="title sectiontitle">Plug-in that overrides the base PDF transformation</h2>
<p class="p">Production uses of DITA-OT typically rely on a custom PDF plug-in to render PDFs that are styled to match
corporate or organizational guidelines. Such customization plug-ins often override the following aspects of
DITA-OT default output:</p>
<ul class="ul">
<li class="li">Generated text strings</li>
<li class="li">XSL templates</li>
<li class="li">XSL-FO attribute sets</li>
</ul>
</section>
</div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/pdf-customization-plugins.html" title="In most cases, PDF output should be customized by creating custom DITA-OT plug-ins that build on the default DITA to PDF transformation. PDF plug-ins can customize covers and page layouts, modify formatting, override the logic of the default PDF plug-in, and much more.">Custom PDF plug-ins</a></div></div></nav></article></main></body></html>

12
dita-ot-3.6/doc/topics/pdf-customization-plugins.html Normal file
View file

@ -0,0 +1,12 @@
<!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="In most cases, PDF output should be customized by creating custom DITA-OT plug-ins that build on the default DITA to PDF transformation. PDF plug-ins can customize covers and page layouts, modify formatting, override the logic of the default PDF plug-in, and much more."><meta name="keywords" content="transformations, PDF, PDF, custom plug-in"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Custom PDF plug-ins</title></head><body id="custom-pdf-plugins"><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 class="active"><a href="../topics/pdf-customization-plugins.html">Custom PDF plug-ins</a><ul><li><a href="../topics/pdf-customization-plugin-types.html">Types of PDF plug-ins</a></li><li><a href="../topics/pdf-plugin-structure.html">PDF plug-in structure</a></li><li><a href="../topics/pdf-customization-example.html">Simple PDF plug-in</a></li><li><a href="../topics/pdf-customization-resources.html">PDF plug-in resources</a></li></ul></li><li><a href="../topics/globalization.html">Globalizing DITA content</a></li><li><a href="../topics/migration.html">Migrating customizations</a></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">Custom PDF plug-ins</h1>
<p class="shortdesc">In most cases, PDF output should be customized by creating custom DITA-OT plug-ins that build on the
default DITA to PDF transformation. PDF plug-ins can customize covers and page layouts, modify formatting, override
the logic of the default PDF plug-in, and much more.</p>
<nav role="navigation" class="related-links"><ul class="ullinks"><li class="link ulchildlink"><strong><a href="../topics/pdf-customization-plugin-types.html">Types of custom PDF plug-ins</a></strong><br>There are two common types of plug-ins: A plug-in that simply sets the DITA-OT parameters to be used when a PDF is generated, and a plug-in that overrides aspects of the base DITA-OT PDF transformation. A plug-in can, of course, do both of these things.</li><li class="link ulchildlink"><strong><a href="../topics/pdf-plugin-structure.html">PDF plug-in structure</a></strong><br>In cases that require substantial customizations, it is often useful to organize the files in a folder structure that mimics the hierarchy of the default PDF plug-in.</li><li class="link ulchildlink"><strong><a href="../topics/pdf-customization-example.html">Example: Creating a simple PDF plug-in</a></strong><br>This scenario walks through the process of creating a very simple plug-in (<code class="ph codeph">com.example.print-pdf</code>) that creates a new transformation type: <span class="keyword option">print-pdf</span>. </li><li class="link ulchildlink"><strong><a href="../topics/pdf-customization-resources.html">Resources for custom PDF plug-ins</a></strong><br>There are several external resources that can help you generate and refine custom PDF plug-ins for DITA Open Toolkit.</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 relconcepts"><strong>Related concepts</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/pdf-customization.html" title="You can adjust various aspects of PDF output by changing parameter settings. For more complex customizations, you can create custom DITA-OT plug-ins.">Customizing PDF output</a></li><li class="linklist"><a class="link" href="../topics/pdf-customization-approaches.html" title="Various methods may be used to customize the PDF output that DITA Open Toolkit produces. Each of these approaches have advantages and shortcomings that should be considered when preparing a customization project.">PDF customization approaches</a></li><li class="linklist"><a class="link" href="../topics/plugin-coding-conventions.html" title="To ensure custom plug-ins work well with the core toolkit code and remain compatible with future releases, the DITA Open Toolkit project recommends that plug-ins use modern development practices and common coding patterns.">Plug-in coding conventions</a></li></ul></div></nav></article></main></body></html>

86
dita-ot-3.6/doc/topics/pdf-customization-resources.html Normal file
View file

@ -0,0 +1,86 @@
<!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="There are several external resources that can help you generate and refine custom PDF plug-ins for DITA Open Toolkit."><meta name="keywords" content="RenderX, plugin generator, Antenna House, Apache FOP, Jarno Elovirta, PDF, fonts, PDF plugin generator"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Resources for custom PDF plug-ins</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><ul><li><a href="../topics/pdf-customization-plugin-types.html">Types of PDF plug-ins</a></li><li><a href="../topics/pdf-plugin-structure.html">PDF plug-in structure</a></li><li><a href="../topics/pdf-customization-example.html">Simple PDF plug-in</a></li><li class="active"><a href="../topics/pdf-customization-resources.html">PDF plug-in resources</a></li></ul></li><li><a href="../topics/globalization.html">Globalizing DITA content</a></li><li><a href="../topics/migration.html">Migrating customizations</a></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">Resources for custom PDF plug-ins</h1>
<div class="body refbody"><p class="shortdesc">There are several external resources that can help you generate and refine custom PDF plug-ins for DITA
Open Toolkit.</p>
<section class="section" id="ID__pdf-plugin-generator"><h2 class="title sectiontitle">PDF Plugin Generator</h2>
<p class="p">This online tool, developed and maintained by Jarno Elovirta, enables you to generate a PDF customization
plug-in automatically.</p>
<p class="p">The application at
<a class="xref" href="http://dita-generator.elovirta.com/" target="_blank" rel="external noopener">dita-generator.elovirta.com</a> walks you through the process of creating a custom PDF plug-in and allows
you to adjust a variety of settings for your PDF output. For example, you can:</p>
<ul class="ul">
<li class="li">Define the target environment, selecting from the most current and two previous versions of DITA-OT</li>
<li class="li">Select the XSL formatting engine (FOP, Antenna House Formatter, or RenderX XEP)</li>
<li class="li">Specify page size, columns, and margins</li>
<li class="li">Select from (limited) options for headers and footers</li>
<li class="li">Specify layout options for chapters</li>
<li class="li">Select formatting for the following publication components:
<ul class="ul">
<li class="li">Normal text</li>
<li class="li">Headings (levels one through four)</li>
<li class="li">Titles for sections and examples</li>
<li class="li">Tables and figures</li>
<li class="li">Notes and examples</li>
<li class="li">Lists (unordered, ordered, and definition)</li>
<li class="li">Code blocks and pre-formatted text</li>
<li class="li">Inline elements such as links and trademarks</li>
</ul>
<p class="p">For each component, you can specify: </p>
<ul class="ul">
<li class="li">Font family, size, weight, and style</li>
<li class="li">Color and background color</li>
<li class="li">Alignment, indentation, spacing, and padding</li>
</ul></li>
</ul>
<div class="note tip note_tip"><span class="note__title">Tip:</span> The PDF Plugin Generator should be your first stop as you start developing a brand-new PDF
customization plug-in.</div>
</section>
<section class="section"><h2 class="title sectiontitle"><cite class="cite">DITA for Print: A DITA Open Toolkit Workbook</cite> (Second Edition, 2017)</h2>
<p class="p">Authored by Leigh W. White, DITA Specialist at IXIASOFT, and published by XML Press, <cite class="cite">DITA for
Print</cite> walks readers through developing a PDF customization from scratch. </p>
<p class="p">Here is an excerpt from the back cover:</p>
<blockquote class="lq"><cite class="cite">DITA for Print</cite> is for anyone who wants to learn how to create PDFs using the DITA Open Toolkit
without learning everything there is to know about XSL-FO, XSLT, or XPath, or even about the DITA Open Toolkit
itself. <cite class="cite">DITA for Print</cite> is written for non-programmers, by a non-programmer, and although it is
written for people who have a good understanding of the DITA standard, you don’t need a technical background to
get custom PDFs up and running quickly.</blockquote>
<p class="p">This is an excellent, long-needed resource that was initially developed in 2013 for DITA-OT 1.8.</p>
<p class="p">The second edition has been revised to cover DITA Open Toolkit Version 2, including customizing the DITA 1.3
troubleshooting topic type, localization strings, bookmarks, and the new back-cover functionality.</p>
<div class="note important note_important"><span class="note__title">Important:</span>
<p class="p">The first edition of <cite class="cite">DITA for Print</cite> recommended copying entire files from the PDF2 plug-in to
your custom plug-in. The DITA-OT project — and the second edition of the book — do not recommend this
practice.</p>
<p class="p">Instead, you should copy only the specific attribute sets and templates that you want to override. Following
this practice will more cleanly isolate your customizations from the DITA-OT code, which will make it easier
for you to update your plug-ins to work with future versions of DITA-OT.</p></div>
</section>
<section class="section"><h2 class="title sectiontitle"><cite class="cite">DITA for Practitioners: Volume 1, Architecture and Technology</cite> (2012)</h2>
<p class="p">Authored by Eliot Kimber and published by XML Press, this seminal resource contains a chapter dedicated to DITA
Open Toolkit: “Running, Configuring, and Customizing the Open Toolkit”. In addition to a robust overview of
DITA-OT customization and extension, the chapter contains a detailed example of customizing a PDF plug-in to
specify 7" × 10" paper size and custom fonts for body text and headers.</p>
<p class="p">The DITA-OT chapter in <cite class="cite">DITA for Practitioners: Volume 1</cite> was written for DITA-OT 1.5.4, which was
the latest stable version at the time it was written.</p>
</section>
</div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/pdf-customization-plugins.html" title="In most cases, PDF output should be customized by creating custom DITA-OT plug-ins that build on the default DITA to PDF transformation. PDF plug-ins can customize covers and page layouts, modify formatting, override the logic of the default PDF plug-in, and much more.">Custom PDF 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/2018/dita-ot_day.html#twisted_xslt_tricks" target="_blank" rel="external noopener" title="Switching from single column to two-column layout is almost impossible using the PDF2 transform and FOP because FOP enforces XSL-FO's rule that only direct children of fo:flow can change the column spanning. Likewise, splitting page sequences to change from portrait to landscape is hard to do with the PDF2 transform because it provides no easy way to change the page sequence within the context of a topic's body (e.g., to put rotated tables on landscape pages). This talk presents a general XSLT technique for splitting a single tree into multiple trees, enabling changing column spanning and splitting page sequences with a minimum of rework of normal templates.">Twisted XSLT Tricks: Making Column Switching Work for FOP</a></li><li class="linklist"><a class="link" href="https://www.oxygenxml.com/events/2014/dita-ot_day.html#DITA_Open_Toolkit_PDF_plugins_without_fuss_muss_or_writing_XSL-FO" target="_blank" rel="external noopener" title="Did you know that you can create customized PDF plugins using an easy online tool? Join Jarno for an overview of his plugin generator, what it produces, and his work developing the dynamic Web interface.">DITA Open Toolkit PDF Plugins Without Fuss, Muss, or Writing XSL-FO</a></li><li class="linklist"><a class="link" href="https://www.oxygenxml.com/events/2014/dita-ot_day.html#PDFs_from_the_DITA_Open_Toolkit" target="_blank" rel="external noopener" title="With a few simple changes, it's possible to give the DITA-OT's default PDF output much of your own look and feel. If you need to develop a DITA proof of concept for your organization, these changes might be all you need to get the ball rolling. Join Leigh to find out what's easy to do, what's not quite so easy to do, and where the real heavy lifting is.">PDFs from the DITA Open Toolkit: The Easy and the Not-so-Easy</a></li></ul></div></nav></article></main></body></html>

28
dita-ot-3.6/doc/topics/pdf-customization.html Normal file
View file

@ -0,0 +1,28 @@
<!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="You can adjust various aspects of PDF output by changing parameter settings. For more complex customizations, you can create custom DITA-OT plug-ins."><meta name="keywords" content="transformations, PDF, PDF, customizing"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Customizing PDF output</title></head><body id="customizing-pdf-output"><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 class="active"><a href="../topics/pdf-customization.html">Customizing PDF</a><ul><li><a href="../topics/pdf-customization-approaches.html">Customization approaches</a></li><li><a href="../topics/pdf2-creating-change-bars.html">Generating revision bars</a></li></ul></li><li><a href="../topics/adding-plugins.html">Adding plug-ins</a></li><li><a href="../topics/custom-plugins.html">Creating plug-ins</a></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">Customizing PDF output</h1>
<div class="body conbody"><p class="shortdesc">You can <span class="ph" id="customizing-pdf-output__shortdesc-ph">adjust various aspects of PDF output by changing parameter settings</span>. For
more complex customizations, you can create custom DITA-OT plug-ins.</p>
<p class="p">For example:</p>
<ul class="ul">
<li class="li">To print the file names of the graphics underneath figures, set <span class="keyword parmname">args.artlbl</span> to
<span class="keyword option">yes.</span></li>
<li class="li">To disable the subsection links on the first page of each chapter, set
<span class="keyword parmname">args.chapter.layout</span> to <span class="keyword option">BASIC</span>.</li>
<li class="li">To change the name of the PDF file to something other than the input map name, set
<span class="keyword parmname">outputFile.base</span> to the desired file name (without the <span class="ph filepath">.pdf</span>
extension).</li>
</ul>
<div class="note note note_note"><span class="note__title">Note:</span> For the full list of settings for PDF output, see
<a class="xref" href="../parameters/parameters-pdf.html" title="Certain parameters are specific to the PDF transformation.">PDF parameters</a>.</div>
</div>
<nav role="navigation" class="related-links"><ul class="ullinks"><li class="link ulchildlink"><strong><a href="../topics/pdf-customization-approaches.html">PDF customization approaches</a></strong><br>Various methods may be used to customize the PDF output that DITA Open Toolkit produces. Each of these approaches have advantages and shortcomings that should be considered when preparing a customization project.</li><li class="link ulchildlink"><strong><a href="../topics/pdf2-creating-change-bars.html">Generating revision bars</a></strong><br>You can generate revision bars in your PDF output by using the <code class="keyword markupname xmlatt">@changebar</code> and <code class="keyword markupname xmlatt">@color</code> attributes of the DITAVAL <code class="keyword markupname xmlelement">&lt;revprop&gt;</code> element.</li></ul><div class="linklist reltasks"><strong>Related tasks</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/pdf-customization-plugins.html" title="In most cases, PDF output should be customized by creating custom DITA-OT plug-ins that build on the default DITA to PDF transformation. PDF plug-ins can customize covers and page layouts, modify formatting, override the logic of the default PDF plug-in, and much more.">Custom PDF plug-ins</a></li></ul></div></nav></article></main></body></html>

93
dita-ot-3.6/doc/topics/pdf-plugin-structure.html Normal file
View file

@ -0,0 +1,93 @@
<!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="In cases that require substantial customizations, it is often useful to organize the files in a folder structure that mimics the hierarchy of the default PDF plug-in."><meta name="keywords" content="languages, adding support for, I18N, plug-in, PDF, font-mappings.xml, fonts, PDF, fonts, index, Customization directory"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>PDF plug-in structure</title></head><body id="pdf-plugin-structure"><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><ul><li><a href="../topics/pdf-customization-plugin-types.html">Types of PDF plug-ins</a></li><li class="active"><a href="../topics/pdf-plugin-structure.html">PDF plug-in structure</a><ul><li><a href="../topics/pdf-plugin-structure_common-artwork.html">Custom artwork</a></li><li><a href="../topics/pdf-plugin-structure_common-index.html">Index configuration</a></li><li><a href="../topics/pdf-plugin-structure_common-vars.html">Variable overrides</a></li><li><a href="../topics/pdf-plugin-structure_fo-attrs.html">Custom attributes</a></li><li><a href="../topics/pdf-plugin-structure_fo-i18n.html">Internationalization</a></li><li><a href="../topics/pdf-plugin-structure_fo-xsl.html">Custom stylesheets</a></li></ul></li><li><a href="../topics/pdf-customization-example.html">Simple PDF plug-in</a></li><li><a href="../topics/pdf-customization-resources.html">PDF plug-in resources</a></li></ul></li><li><a href="../topics/globalization.html">Globalizing DITA content</a></li><li><a href="../topics/migration.html">Migrating customizations</a></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">PDF plug-in structure</h1>
<div class="body conbody"><p class="shortdesc">In cases that require substantial customizations, it is often useful to organize the files in a folder
structure that mimics the hierarchy of the default PDF plug-in.</p>
<div class="note note note_note"><span class="note__title">Note:</span> For simpler customizations, you may want to structure your plug-in differently, but the information in this
topic may help you to locate the files you need to customize.</div>
<p class="p">The original Idiom plug-in used its own extension mechanism to provide overrides to the PDF transformation. With
this approach, a dedicated <span class="ph filepath">Customization</span> folder within the plug-in was used as a
customization layer to store files that override the default behavior.</p>
<p class="p">While this method is no longer recommended, the same organization principles can be used in custom PDF plug-ins
to facilitate comparisons with the default settings in the base PDF plug-in and make it easier to migrate
customizations to new toolkit versions.</p>
<figure class="fig fignone"><figcaption><span class="fig--title-label">Figure 1. </span>Default <span class="ph filepath">Customization</span> folder content</figcaption>
<pre class="pre codeblock"><code>.
├── build.properties.orig
├── catalog.xml.orig
└── fo/
├── attrs/
│ └── custom.xsl.orig
└── xsl/
└── custom.xsl.orig</code></pre>
</figure>
<p class="p">To begin creating a new custom plug-in, you can copy the contents of the customization layer template in
<span class="ph filepath">plugins/org.dita.pdf2/Customization</span> to a new folder that will serve as your new custom
plug-in folder, such as <span class="ph filepath">plugins/com.company.pdf</span>.</p>
<p class="p">To mimic the hierarchy of the default PDF plug-in, you may want to add a <span class="ph filepath">cfg/</span> subfolder and
move the contents of the <span class="ph filepath">fo/</span> folder to <span class="ph filepath">cfg/fo/</span>.</p>
<p class="p">DITA-OT provides template files that you can start with throughout the <span class="ph filepath">Customization</span>
directory structure. These files end in the suffix <code class="ph codeph">.orig</code> (for example,
<span class="ph filepath">catalog.xml.orig</span>). To enable these files, remove the <code class="ph codeph">.orig</code> suffix from the
copies in your new custom plug-in folder. (For example, rename <span class="ph filepath">catalog.xml.orig</span> to
<span class="ph filepath">catalog.xml</span>).</p>
<p class="p">You can then make modifications to the copy in your custom plug-in folder, and copy any other files from the
default PDF plug-in that you need to override, such as the page layouts in
<span class="ph filepath">layout-masters.xsl</span>, or the <span class="ph filepath">font-mappings.xml</span> file that tells your PDF
renderer which fonts to use and where to find them.</p>
<div class="note important note_important"><span class="note__title">Important:</span> Wherever possible, avoid copying entire XSL files from the PDF2 plug-in to your custom
plug-in. Instead, copy only the specific attribute sets and templates that you want to override. For details, see
<a class="xref" href="plugin-coding-conventions.html" title="To ensure custom plug-ins work well with the core toolkit code and remain compatible with future releases, the DITA Open Toolkit project recommends that plug-ins use modern development practices and common coding patterns.">Plug-in coding conventions</a>.</div>
<p class="p">Things you can currently override include:</p>
<ul class="ul">
<li class="li">Custom XSL via <span class="ph filepath">xsl/custom.xsl</span> and <span class="ph filepath">attrs/custom.xsl</span></li>
<li class="li">Layout overrides via <span class="ph filepath">layout-masters.xsl</span></li>
<li class="li">Font overrides via <span class="ph filepath">font-mappings.xml</span></li>
<li class="li">Per-locale variable overrides via <span class="ph filepath">common/vars/[language].xml</span></li>
<li class="li">I18N configuration via <span class="ph filepath">i18n/[language].xml</span></li>
<li class="li">Index configuration via <span class="ph filepath">index/[language].xml</span></li>
</ul>
<p class="p">When customizing any of these areas, modify the relevant file(s) in your custom plug-in folder. Then, to enable
the changes in the publishing process, you find the corresponding entry for each file you modified in the
<span class="ph filepath">catalog.xml</span> file.</p>
<p class="p">It should look like this:</p>
<pre class="pre codeblock language-xml"><code>&lt;!--uri name="cfg:fo/attrs/custom.xsl" uri="fo/attrs/custom.xsl"/--&gt;</code></pre>
<p class="p">Remove the comment markers <code class="ph codeph">!--</code> and <code class="ph codeph">--</code> to enable the change:</p>
<pre class="pre codeblock language-xml"><code>&lt;uri name="cfg:fo/attrs/custom.xsl" uri="fo/attrs/custom.xsl"/&gt;</code></pre>
<p class="p">Your customization should now be enabled as part of the publishing process.</p>
<figure class="fig fignone"><figcaption><span class="fig--title-label">Figure 2. </span>Sample custom plug-in structure</figcaption>
<pre class="pre codeblock"><code>.
├── plugin.xml
├── ant-include.xml
└── cfg/
├── catalog.xml
├── common/
│ ├── artwork/
│ │ ├── logo.svg
│ └── vars/
│ ├── strings.xml
│ ├── en.xml
└── fo/
├── attrs/
│ ├── custom.xsl
├── font-mappings.xml
├── layout-masters.xsl
└── xsl/
└── custom.xsl</code></pre>
</figure>
<p class="p">When your custom plug-in is installed, the files in its subfolders will override the out-of-the-box settings from
their counterparts in <span class="ph filepath">org.dita.pdf2/cfg/fo/attrs</span> and
<span class="ph filepath">org.dita.pdf2/xsl/fo</span>.</p>
<p class="p">The following topics describe the contents of the base PDF plug-in subfolders and provide additional information
on customizing various aspects of the default PDF output.</p>
</div>
<nav role="navigation" class="related-links"><ul class="ullinks"><li class="link ulchildlink"><strong><a href="../topics/pdf-plugin-structure_common-artwork.html">Custom artwork</a></strong><br>The <span class="ph filepath">common/artwork</span> folder houses custom artwork files that override the standard icons in <span class="ph filepath">org.dita.pdf2/cfg/common/artwork</span>.</li><li class="link ulchildlink"><strong><a href="../topics/pdf-plugin-structure_common-index.html">Index configuration</a></strong><br>The <span class="ph filepath">common/index</span> folder houses custom index definition files that override the standard definitions in <span class="ph filepath">org.dita.pdf2/cfg/common/index</span>.</li><li class="link ulchildlink"><strong><a href="../topics/pdf-plugin-structure_common-vars.html">Variable overrides</a></strong><br>The <span class="ph filepath">common/vars</span> folder houses custom variable definitions that override the standard definitions in <span class="ph filepath">org.dita.pdf2/cfg/common/vars</span>. </li><li class="link ulchildlink"><strong><a href="../topics/pdf-plugin-structure_fo-attrs.html">Custom attributes</a></strong><br>The <span class="ph filepath">fo/attrs</span> folder houses custom attribute configuration files that override the standard attributes in <span class="ph filepath">org.dita.pdf2/cfg/fo/attrs</span>.</li><li class="link ulchildlink"><strong><a href="../topics/pdf-plugin-structure_fo-i18n.html">Internationalization configuration</a></strong><br>The <span class="ph filepath">fo/i18n</span> folder houses custom internationalization files that override the standard configurations in <span class="ph filepath">org.dita.pdf2/cfg/fo/i18n</span>.</li><li class="link ulchildlink"><strong><a href="../topics/pdf-plugin-structure_fo-xsl.html">Custom stylesheets</a></strong><br>The <span class="ph filepath">fo/xsl</span> folder houses custom stylesheet files that override the default stylesheets in <span class="ph filepath">org.dita.pdf2/xsl/fo</span>.</li></ul><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/pdf-customization-plugins.html" title="In most cases, PDF output should be customized by creating custom DITA-OT plug-ins that build on the default DITA to PDF transformation. PDF plug-ins can customize covers and page layouts, modify formatting, override the logic of the default PDF plug-in, and much more.">Custom PDF plug-ins</a></div></div></nav></article></main></body></html>

21
dita-ot-3.6/doc/topics/pdf-plugin-structure_common-artwork.html Normal file
View file

@ -0,0 +1,21 @@
<!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="The common/artwork folder houses custom artwork files that override the standard icons in org.dita.pdf2/cfg/common/artwork."><meta name="keywords" content=", note, type, locale"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Custom artwork</title></head><body id="custom_artwork_the_common_artwork_folder"><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><ul><li><a href="../topics/pdf-customization-plugin-types.html">Types of PDF plug-ins</a></li><li><a href="../topics/pdf-plugin-structure.html">PDF plug-in structure</a><ul><li class="active"><a href="../topics/pdf-plugin-structure_common-artwork.html">Custom artwork</a></li><li><a href="../topics/pdf-plugin-structure_common-index.html">Index configuration</a></li><li><a href="../topics/pdf-plugin-structure_common-vars.html">Variable overrides</a></li><li><a href="../topics/pdf-plugin-structure_fo-attrs.html">Custom attributes</a></li><li><a href="../topics/pdf-plugin-structure_fo-i18n.html">Internationalization</a></li><li><a href="../topics/pdf-plugin-structure_fo-xsl.html">Custom stylesheets</a></li></ul></li><li><a href="../topics/pdf-customization-example.html">Simple PDF plug-in</a></li><li><a href="../topics/pdf-customization-resources.html">PDF plug-in resources</a></li></ul></li><li><a href="../topics/globalization.html">Globalizing DITA content</a></li><li><a href="../topics/migration.html">Migrating customizations</a></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">Custom artwork</h1>
<div class="body"><p class="shortdesc">The <span class="ph filepath">common/artwork</span> folder houses custom artwork files that override the standard icons
in <span class="ph filepath">org.dita.pdf2/cfg/common/artwork</span>.</p>
<p class="p">These files are used to graphically identify different types of DITA <code class="keyword markupname xmlelement">&lt;note&gt;</code> element.</p>
<p class="p">The mapping between <code class="keyword markupname xmlelement">&lt;note&gt;</code> type and graphic is contained in the common variables file
<span class="ph filepath">org.dita.pdf2/cfg/common/vars/commonvariables.xml</span>.</p>
<p class="p">The variables that control <code class="keyword markupname xmlelement">&lt;note&gt;</code> graphics all follow the form</p>
<pre class="pre codeblock language-xml"><code>&lt;variable id="<var class="keyword varname">{type}</var> Note Image Path"&gt; <var class="keyword varname">{path to image file}</var> &lt;/variable&gt;</code></pre>
<p class="p">where <var class="keyword varname">{type}</var> contains a possible value for the <code class="keyword markupname xmlelement">&lt;note&gt;</code>
<code class="keyword markupname xmlatt">@type</code> attribute and <var class="keyword varname">{path to image file}</var> is the path to the note icon
image.</p>
</div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/pdf-plugin-structure.html" title="In cases that require substantial customizations, it is often useful to organize the files in a folder structure that mimics the hierarchy of the default PDF plug-in.">PDF plug-in structure</a></div></div><div class="linklist relinfo"><strong>Related information</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/pdf-plugin-structure_common-index.html" title="The common/index folder houses custom index definition files that override the standard definitions in org.dita.pdf2/cfg/common/index.">Index configuration</a></li><li class="linklist"><a class="link" href="../topics/pdf-plugin-structure_common-vars.html" title="The common/vars folder houses custom variable definitions that override the standard definitions in org.dita.pdf2/cfg/common/vars.">Variable overrides</a></li><li class="linklist"><a class="link" href="../topics/pdf-plugin-structure_fo-attrs.html" title="The fo/attrs folder houses custom attribute configuration files that override the standard attributes in org.dita.pdf2/cfg/fo/attrs.">Custom attributes</a></li><li class="linklist"><a class="link" href="../topics/pdf-plugin-structure_fo-i18n.html" title="The fo/i18n folder houses custom internationalization files that override the standard configurations in org.dita.pdf2/cfg/fo/i18n.">Internationalization configuration</a></li><li class="linklist"><a class="link" href="../topics/pdf-plugin-structure_fo-xsl.html" title="The fo/xsl folder houses custom stylesheet files that override the default stylesheets in org.dita.pdf2/xsl/fo.">Custom stylesheets</a></li></ul></div></nav></article></main></body></html>

25
dita-ot-3.6/doc/topics/pdf-plugin-structure_common-index.html Normal file
View file

@ -0,0 +1,25 @@
<!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="The common/index folder houses custom index definition files that override the standard definitions in org.dita.pdf2/cfg/common/index."><meta name="keywords" content=", index.group, char.set, languages, ISO 639-1, Portuguese, index, PDF, catalog, catalog.xml, index configuration"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Index configuration</title></head><body id="index_configuration_the_common_index_folder"><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><ul><li><a href="../topics/pdf-customization-plugin-types.html">Types of PDF plug-ins</a></li><li><a href="../topics/pdf-plugin-structure.html">PDF plug-in structure</a><ul><li><a href="../topics/pdf-plugin-structure_common-artwork.html">Custom artwork</a></li><li class="active"><a href="../topics/pdf-plugin-structure_common-index.html">Index configuration</a></li><li><a href="../topics/pdf-plugin-structure_common-vars.html">Variable overrides</a></li><li><a href="../topics/pdf-plugin-structure_fo-attrs.html">Custom attributes</a></li><li><a href="../topics/pdf-plugin-structure_fo-i18n.html">Internationalization</a></li><li><a href="../topics/pdf-plugin-structure_fo-xsl.html">Custom stylesheets</a></li></ul></li><li><a href="../topics/pdf-customization-example.html">Simple PDF plug-in</a></li><li><a href="../topics/pdf-customization-resources.html">PDF plug-in resources</a></li></ul></li><li><a href="../topics/globalization.html">Globalizing DITA content</a></li><li><a href="../topics/migration.html">Migrating customizations</a></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">Index configuration</h1>
<div class="body"><p class="shortdesc">The <span class="ph filepath">common/index</span> folder houses custom index definition files that override the
standard definitions in <span class="ph filepath">org.dita.pdf2/cfg/common/index</span>.</p>
<p class="p">Each file contains data for a single language, and should take that language’s ISO 639-1 language designator as
its name (for example, <span class="ph filepath">pt.xml</span> for Portuguese). If necessary, locale-specific customizations
can be provided by adding a region designator to the file name (for example, <span class="ph filepath">pt_BR.xml</span> for
Brazilian Portuguese).</p>
<p class="p">The index files consist of <code class="keyword markupname xmlelement">&lt;index.group&gt;</code> elements which contain sorting information on one
or more characters. Index groups are listed in sort order (“specials” before numbers, numbers before the letter
‘A‘, etc), and the <code class="keyword markupname xmlelement">&lt;char.set&gt;</code> entries they contain are also listed in sort order (uppercase
before lowercase).</p>
<p class="p">The best way to start editing a custom index file is by making a copy of the original from
<span class="ph filepath">org.dita.pdf2/cfg/common/index</span> and making changes as desired.</p>
<p class="p">In order to apply a custom index definition to your publishing outputs, edit <span class="ph filepath">catalog.xml</span> and
uncomment the appropriate entry in the “Index configuration override entries” section.</p>
</div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/pdf-plugin-structure.html" title="In cases that require substantial customizations, it is often useful to organize the files in a folder structure that mimics the hierarchy of the default PDF plug-in.">PDF plug-in structure</a></div></div><div class="linklist relinfo"><strong>Related information</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/pdf-plugin-structure_common-artwork.html" title="The common/artwork folder houses custom artwork files that override the standard icons in org.dita.pdf2/cfg/common/artwork.">Custom artwork</a></li><li class="linklist"><a class="link" href="../topics/pdf-plugin-structure_common-vars.html" title="The common/vars folder houses custom variable definitions that override the standard definitions in org.dita.pdf2/cfg/common/vars.">Variable overrides</a></li><li class="linklist"><a class="link" href="../topics/pdf-plugin-structure_fo-attrs.html" title="The fo/attrs folder houses custom attribute configuration files that override the standard attributes in org.dita.pdf2/cfg/fo/attrs.">Custom attributes</a></li><li class="linklist"><a class="link" href="../topics/pdf-plugin-structure_fo-i18n.html" title="The fo/i18n folder houses custom internationalization files that override the standard configurations in org.dita.pdf2/cfg/fo/i18n.">Internationalization configuration</a></li><li class="linklist"><a class="link" href="../topics/pdf-plugin-structure_fo-xsl.html" title="The fo/xsl folder houses custom stylesheet files that override the default stylesheets in org.dita.pdf2/xsl/fo.">Custom stylesheets</a></li></ul></div></nav></article></main></body></html>

32
dita-ot-3.6/doc/topics/pdf-plugin-structure_common-vars.html Normal file
View file

@ -0,0 +1,32 @@
<!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="The common/vars folder houses custom variable definitions that override the standard definitions in org.dita.pdf2/cfg/common/vars."><meta name="keywords" content=", variable, param, , id, variables, overriding, languages, adding support for, ISO 639-1"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Variable overrides</title></head><body id="variable_overrides_the_common_vars_folder"><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><ul><li><a href="../topics/pdf-customization-plugin-types.html">Types of PDF plug-ins</a></li><li><a href="../topics/pdf-plugin-structure.html">PDF plug-in structure</a><ul><li><a href="../topics/pdf-plugin-structure_common-artwork.html">Custom artwork</a></li><li><a href="../topics/pdf-plugin-structure_common-index.html">Index configuration</a></li><li class="active"><a href="../topics/pdf-plugin-structure_common-vars.html">Variable overrides</a></li><li><a href="../topics/pdf-plugin-structure_fo-attrs.html">Custom attributes</a></li><li><a href="../topics/pdf-plugin-structure_fo-i18n.html">Internationalization</a></li><li><a href="../topics/pdf-plugin-structure_fo-xsl.html">Custom stylesheets</a></li></ul></li><li><a href="../topics/pdf-customization-example.html">Simple PDF plug-in</a></li><li><a href="../topics/pdf-customization-resources.html">PDF plug-in resources</a></li></ul></li><li><a href="../topics/globalization.html">Globalizing DITA content</a></li><li><a href="../topics/migration.html">Migrating customizations</a></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">Variable overrides</h1>
<div class="body"><p class="shortdesc">The <span class="ph filepath">common/vars</span> folder houses custom variable definitions that override the standard
definitions in <span class="ph filepath">org.dita.pdf2/cfg/common/vars</span>. </p>
<p class="p">As with index configuration, each file contains data for a single language, and should take that language’s ISO
639-1 language designator as its name.</p>
<p class="p">Variable files contain a set of <code class="keyword markupname xmlelement">&lt;variable&gt;</code> elements, identified by their
<code class="keyword markupname xmlatt">@id</code> attribute. The variable definitions are used to store static text that is used as part of
the published outputs. For example, page headers, hyperlinks, etc. The id attribute for each variable should make
it clear how the variable text is being used.</p>
<p class="p">Some variables contain <code class="keyword markupname xmlelement">&lt;param&gt;</code> elements which indicate parameter values that are
substituted at publish time by the XSL. For example, a page number that is being generated as part of the
publishing process might be identified by &amp;lt;param ref-name="number"/&amp;gt; When editing or translating a
variable file, these should be included in the translation, though they can be moved and rearranged within the
<code class="keyword markupname xmlelement">&lt;variable&gt;</code> content as needed.</p>
<p class="p">The best way to start editing a custom variables file is by making a copy of the original from
<span class="ph filepath">org.dita.pdf2/cfg/common/vars</span> and making changes as desired. When adding a new language,
start from an existing language’s list of variables and translate each entry as needed.</p>
<p class="p">Note that unchanged <code class="keyword markupname xmlelement">&lt;variable&gt;</code> elements can be omitted: the custom variables file need
only include those <code class="keyword markupname xmlelement">&lt;variable&gt;</code> elements which you have modified. Variables not found in the
custom file will are taken from the standard variable files.</p>
<p class="p">Applying a custom variable does not require modifying the <span class="ph filepath">catalog.xml</span> file. The publishing
process will automatically use any custom variables definitions in place of the original ones.</p>
</div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/pdf-plugin-structure.html" title="In cases that require substantial customizations, it is often useful to organize the files in a folder structure that mimics the hierarchy of the default PDF plug-in.">PDF plug-in structure</a></div></div><div class="linklist relinfo"><strong>Related information</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/pdf-plugin-structure_common-artwork.html" title="The common/artwork folder houses custom artwork files that override the standard icons in org.dita.pdf2/cfg/common/artwork.">Custom artwork</a></li><li class="linklist"><a class="link" href="../topics/pdf-plugin-structure_common-index.html" title="The common/index folder houses custom index definition files that override the standard definitions in org.dita.pdf2/cfg/common/index.">Index configuration</a></li><li class="linklist"><a class="link" href="../topics/pdf-plugin-structure_fo-attrs.html" title="The fo/attrs folder houses custom attribute configuration files that override the standard attributes in org.dita.pdf2/cfg/fo/attrs.">Custom attributes</a></li><li class="linklist"><a class="link" href="../topics/pdf-plugin-structure_fo-i18n.html" title="The fo/i18n folder houses custom internationalization files that override the standard configurations in org.dita.pdf2/cfg/fo/i18n.">Internationalization configuration</a></li><li class="linklist"><a class="link" href="../topics/pdf-plugin-structure_fo-xsl.html" title="The fo/xsl folder houses custom stylesheet files that override the default stylesheets in org.dita.pdf2/xsl/fo.">Custom stylesheets</a></li></ul></div></nav></article></main></body></html>

18
dita-ot-3.6/doc/topics/pdf-plugin-structure_fo-attrs.html Normal file
View file

@ -0,0 +1,18 @@
<!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="The fo/attrs folder houses custom attribute configuration files that override the standard attributes in org.dita.pdf2/cfg/fo/attrs."><meta name="keywords" content="fonts, PDF, PDF, fonts, index, tables, index, tables, tables.attr.xsl, index-attr.xsl, tables-attr.xsl"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Custom attributes</title></head><body id="custom_attributes_the_fo_attrs_folder"><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><ul><li><a href="../topics/pdf-customization-plugin-types.html">Types of PDF plug-ins</a></li><li><a href="../topics/pdf-plugin-structure.html">PDF plug-in structure</a><ul><li><a href="../topics/pdf-plugin-structure_common-artwork.html">Custom artwork</a></li><li><a href="../topics/pdf-plugin-structure_common-index.html">Index configuration</a></li><li><a href="../topics/pdf-plugin-structure_common-vars.html">Variable overrides</a></li><li class="active"><a href="../topics/pdf-plugin-structure_fo-attrs.html">Custom attributes</a></li><li><a href="../topics/pdf-plugin-structure_fo-i18n.html">Internationalization</a></li><li><a href="../topics/pdf-plugin-structure_fo-xsl.html">Custom stylesheets</a></li></ul></li><li><a href="../topics/pdf-customization-example.html">Simple PDF plug-in</a></li><li><a href="../topics/pdf-customization-resources.html">PDF plug-in resources</a></li></ul></li><li><a href="../topics/globalization.html">Globalizing DITA content</a></li><li><a href="../topics/migration.html">Migrating customizations</a></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">Custom attributes</h1>
<div class="body"><p class="shortdesc">The <span class="ph filepath">fo/attrs</span> folder houses custom attribute configuration files that override the
standard attributes in <span class="ph filepath">org.dita.pdf2/cfg/fo/attrs</span>.</p>
<p class="p">These files define the appearance of different elements in XML assets when they are rendered to PDF output. The
different DITA elements are organized into files by element type – index-related definitions in
<span class="ph filepath">index-attr.xsl</span>, table-related definitions in <span class="ph filepath">tables-attr.xsl</span>, etc.</p>
<p class="p">The XSL attribute sets defined in these files can be used to override the presentation of DITA elements,
including font size, color, spacing, etc.</p>
</div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/pdf-plugin-structure.html" title="In cases that require substantial customizations, it is often useful to organize the files in a folder structure that mimics the hierarchy of the default PDF plug-in.">PDF plug-in structure</a></div></div><div class="linklist relinfo"><strong>Related information</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/pdf-plugin-structure_common-artwork.html" title="The common/artwork folder houses custom artwork files that override the standard icons in org.dita.pdf2/cfg/common/artwork.">Custom artwork</a></li><li class="linklist"><a class="link" href="../topics/pdf-plugin-structure_common-index.html" title="The common/index folder houses custom index definition files that override the standard definitions in org.dita.pdf2/cfg/common/index.">Index configuration</a></li><li class="linklist"><a class="link" href="../topics/pdf-plugin-structure_common-vars.html" title="The common/vars folder houses custom variable definitions that override the standard definitions in org.dita.pdf2/cfg/common/vars.">Variable overrides</a></li><li class="linklist"><a class="link" href="../topics/pdf-plugin-structure_fo-i18n.html" title="The fo/i18n folder houses custom internationalization files that override the standard configurations in org.dita.pdf2/cfg/fo/i18n.">Internationalization configuration</a></li><li class="linklist"><a class="link" href="../topics/pdf-plugin-structure_fo-xsl.html" title="The fo/xsl folder houses custom stylesheet files that override the default stylesheets in org.dita.pdf2/xsl/fo.">Custom stylesheets</a></li></ul></div></nav></article></main></body></html>

22
dita-ot-3.6/doc/topics/pdf-plugin-structure_fo-i18n.html Normal file
View file

@ -0,0 +1,22 @@
<!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="The fo/i18n folder houses custom internationalization files that override the standard configurations in org.dita.pdf2/cfg/fo/i18n."><meta name="keywords" content="languages, adding support for, ISO 639-1, I18N, languages, locale, args.dita.locale, catalog, catalog.xml, adding languages"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Internationalization configuration</title></head><body id="internationalization_configuration_the_fo_i18n_folder"><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><ul><li><a href="../topics/pdf-customization-plugin-types.html">Types of PDF plug-ins</a></li><li><a href="../topics/pdf-plugin-structure.html">PDF plug-in structure</a><ul><li><a href="../topics/pdf-plugin-structure_common-artwork.html">Custom artwork</a></li><li><a href="../topics/pdf-plugin-structure_common-index.html">Index configuration</a></li><li><a href="../topics/pdf-plugin-structure_common-vars.html">Variable overrides</a></li><li><a href="../topics/pdf-plugin-structure_fo-attrs.html">Custom attributes</a></li><li class="active"><a href="../topics/pdf-plugin-structure_fo-i18n.html">Internationalization</a></li><li><a href="../topics/pdf-plugin-structure_fo-xsl.html">Custom stylesheets</a></li></ul></li><li><a href="../topics/pdf-customization-example.html">Simple PDF plug-in</a></li><li><a href="../topics/pdf-customization-resources.html">PDF plug-in resources</a></li></ul></li><li><a href="../topics/globalization.html">Globalizing DITA content</a></li><li><a href="../topics/migration.html">Migrating customizations</a></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">Internationalization configuration</h1>
<div class="body"><p class="shortdesc">The <span class="ph filepath">fo/i18n</span> folder houses custom internationalization files that override the standard
configurations in <span class="ph filepath">org.dita.pdf2/cfg/fo/i18n</span>.</p>
<p class="p">As with index configuration and variable overrides, each file contains data for a single language, and should
take that language’s ISO 639-1 language designator as its name. </p>
<p class="p">Each configuration file contains mappings of certain symbols to the Unicode codepoint which should be used to
represent them in the given locale.</p>
<p class="p">The best way to start editing a custom configuration is by making a copy of the original from
<span class="ph filepath">org.dita.pdf2/cfg/fo/i18n</span> and making changes as desired.</p>
<p class="p">In order to apply a custom configuration to your publishing outputs, edit <span class="ph filepath">catalog.xml</span> and
uncomment the appropriate entry in the “I18N configuration override entries” section.</p>
</div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/pdf-plugin-structure.html" title="In cases that require substantial customizations, it is often useful to organize the files in a folder structure that mimics the hierarchy of the default PDF plug-in.">PDF plug-in structure</a></div></div><div class="linklist relinfo"><strong>Related information</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/pdf-plugin-structure_common-artwork.html" title="The common/artwork folder houses custom artwork files that override the standard icons in org.dita.pdf2/cfg/common/artwork.">Custom artwork</a></li><li class="linklist"><a class="link" href="../topics/pdf-plugin-structure_common-index.html" title="The common/index folder houses custom index definition files that override the standard definitions in org.dita.pdf2/cfg/common/index.">Index configuration</a></li><li class="linklist"><a class="link" href="../topics/pdf-plugin-structure_common-vars.html" title="The common/vars folder houses custom variable definitions that override the standard definitions in org.dita.pdf2/cfg/common/vars.">Variable overrides</a></li><li class="linklist"><a class="link" href="../topics/pdf-plugin-structure_fo-attrs.html" title="The fo/attrs folder houses custom attribute configuration files that override the standard attributes in org.dita.pdf2/cfg/fo/attrs.">Custom attributes</a></li><li class="linklist"><a class="link" href="../topics/pdf-plugin-structure_fo-xsl.html" title="The fo/xsl folder houses custom stylesheet files that override the default stylesheets in org.dita.pdf2/xsl/fo.">Custom stylesheets</a></li></ul></div></nav></article></main></body></html>

15
dita-ot-3.6/doc/topics/pdf-plugin-structure_fo-xsl.html Normal file
View file

@ -0,0 +1,15 @@
<!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="The fo/xsl folder houses custom stylesheet files that override the default stylesheets in org.dita.pdf2/xsl/fo."><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Custom stylesheets</title></head><body id="custom_stylesheets_the_fo_xsl_folder"><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><ul><li><a href="../topics/pdf-customization-plugin-types.html">Types of PDF plug-ins</a></li><li><a href="../topics/pdf-plugin-structure.html">PDF plug-in structure</a><ul><li><a href="../topics/pdf-plugin-structure_common-artwork.html">Custom artwork</a></li><li><a href="../topics/pdf-plugin-structure_common-index.html">Index configuration</a></li><li><a href="../topics/pdf-plugin-structure_common-vars.html">Variable overrides</a></li><li><a href="../topics/pdf-plugin-structure_fo-attrs.html">Custom attributes</a></li><li><a href="../topics/pdf-plugin-structure_fo-i18n.html">Internationalization</a></li><li class="active"><a href="../topics/pdf-plugin-structure_fo-xsl.html">Custom stylesheets</a></li></ul></li><li><a href="../topics/pdf-customization-example.html">Simple PDF plug-in</a></li><li><a href="../topics/pdf-customization-resources.html">PDF plug-in resources</a></li></ul></li><li><a href="../topics/globalization.html">Globalizing DITA content</a></li><li><a href="../topics/migration.html">Migrating customizations</a></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">Custom stylesheets</h1>
<div class="body"><p class="shortdesc">The <span class="ph filepath">fo/xsl</span> folder houses custom stylesheet files that override the default
stylesheets in <span class="ph filepath">org.dita.pdf2/xsl/fo</span>.</p>
<p class="p">You can use custom stylesheets to implement additional processing routines or adjust the output generated by
the default toolkit processing.</p>
</div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/pdf-plugin-structure.html" title="In cases that require substantial customizations, it is often useful to organize the files in a folder structure that mimics the hierarchy of the default PDF plug-in.">PDF plug-in structure</a></div></div><div class="linklist relinfo"><strong>Related information</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/pdf-plugin-structure_common-artwork.html" title="The common/artwork folder houses custom artwork files that override the standard icons in org.dita.pdf2/cfg/common/artwork.">Custom artwork</a></li><li class="linklist"><a class="link" href="../topics/pdf-plugin-structure_common-index.html" title="The common/index folder houses custom index definition files that override the standard definitions in org.dita.pdf2/cfg/common/index.">Index configuration</a></li><li class="linklist"><a class="link" href="../topics/pdf-plugin-structure_common-vars.html" title="The common/vars folder houses custom variable definitions that override the standard definitions in org.dita.pdf2/cfg/common/vars.">Variable overrides</a></li><li class="linklist"><a class="link" href="../topics/pdf-plugin-structure_fo-attrs.html" title="The fo/attrs folder houses custom attribute configuration files that override the standard attributes in org.dita.pdf2/cfg/fo/attrs.">Custom attributes</a></li><li class="linklist"><a class="link" href="../topics/pdf-plugin-structure_fo-i18n.html" title="The fo/i18n folder houses custom internationalization files that override the standard configurations in org.dita.pdf2/cfg/fo/i18n.">Internationalization configuration</a></li></ul></div></nav></article></main></body></html>

48
dita-ot-3.6/doc/topics/pdf2-creating-change-bars.html Normal file
View file

@ -0,0 +1,48 @@
<!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="You can generate revision bars in your PDF output by using the changebar and color attributes of the DITAVAL revprop element."><meta name="keywords" content=", revprop, changebar, color, DITAVAL, change bars, RenderX, Antenna House, Apache FOP, PDF, transformations"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Generating revision bars</title></head><body id="concept_gsc_vcf_vs"><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><ul><li><a href="../topics/pdf-customization-approaches.html">Customization approaches</a></li><li class="active"><a href="../topics/pdf2-creating-change-bars.html">Generating revision bars</a></li></ul></li><li><a href="../topics/adding-plugins.html">Adding plug-ins</a></li><li><a href="../topics/custom-plugins.html">Creating plug-ins</a></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">Generating revision bars</h1>
<div class="body conbody"><p class="shortdesc">You can generate revision bars in your PDF output by using the <code class="keyword markupname xmlatt">@changebar</code> and
<code class="keyword markupname xmlatt">@color</code> attributes of the DITAVAL <code class="keyword markupname xmlelement">&lt;revprop&gt;</code> element.</p>
<div class="p">The DITA
<a class="xref" href="http://docs.oasis-open.org/dita/dita/v1.3/errata02/os/complete/part3-all-inclusive/langRef/ditaval/ditaval-revprop.html#ditaval-revprop" target="_blank" rel="external noopener">specification</a> for the <code class="keyword markupname xmlatt">@changebar</code> attribute of the
<code class="keyword markupname xmlelement">&lt;revprop&gt;</code> element simply says:<blockquote class="lq">
<dl class="dl">
<dt class="dt dlterm"><code class="keyword markupname xmlatt">@changebar</code></dt>
<dd class="dd">When flag has been set, specify a changebar color, style, or character, according to the changebar
support of the target output format. If flag has not been set, this attribute is ignored.</dd>
</dl>
</blockquote></div>
<p class="p">The current version of DITA Open Toolkit uses two <code class="keyword markupname xmlelement">&lt;revprop&gt;</code> attribute values to define
revision bars:</p>
<ul class="ul">
<li class="li">
<p class="p">The <code class="keyword markupname xmlatt">@changebar</code> attribute value defines the style to use for the line. The list of possible
values is the same as for other XSL-FO rules (see
<a class="xref" href="http://www.w3.org/TR/xsl/#change-bar-style" target="_blank" rel="external noopener">@change-bar-style</a>). The default value is <span class="keyword option">groove</span>.</p></li>
<li class="li">
<p class="p">The <code class="keyword markupname xmlatt">@color</code> attribute value specifies the change bar color using any color value recognized by
XSL-FO, including the usual color names or a hex color value. The default value is
<span class="keyword option">black</span>.</p></li>
</ul>
<figure class="fig fignone"><figcaption><span class="fig--title-label">Figure 1. </span>Sample revision bar configuration</figcaption>
<pre class="pre codeblock language-xml"><code>&lt;revprop action="flag" changebar="solid" color="green"/&gt;</code></pre>
</figure>
<p class="p">DITA-OT uses a default offset of 2&nbsp;mm to place the revision bar near the edge of the text column. The offset,
placement and width are not currently configurable via attribute values.</p>
<p class="p">XSL-FO 1.1 does not provide for revision bars that are not rules, so there is no way to get text revision
indicators instead of rules, for example, using a number in place of a rule. Antenna House Formatter provides a
proprietary extension to enable this, but the DITA-OT PDF transformation does not take advantage of it.</p>
</div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/pdf-customization.html" title="You can adjust various aspects of PDF output by changing parameter settings. For more complex customizations, you can create custom DITA-OT plug-ins.">Customizing PDF output</a></div></div></nav></article></main></body></html>

118
dita-ot-3.6/doc/topics/plugin-addgeneratedtext.html Normal file
View file

@ -0,0 +1,118 @@
<!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="Generated text is the term for strings that are automatically added by the build, such as &#34;Note&#34; before the contents of a note element."><meta name="keywords" content=", note, xml:lang, languages, adding support for, English, Icelandic, Russian, Vietnamese, Gaelic, strings, generated text, draft, localizing generated text"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Customizing generated text</title></head><body id="plugin-addgeneratedtext"><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><ul><li><a href="../topics/globalization-support.html">Globalization support</a></li><li class="active"><a href="../topics/plugin-addgeneratedtext.html">Customizing generated text</a></li><li><a href="../topics/globalization-languages.html">Supported languages</a></li></ul></li><li><a href="../topics/migration.html">Migrating customizations</a></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">Customizing generated text</h1>
<div class="body refbody"><p class="shortdesc">Generated text is the term for strings that are automatically added by the build, such as "Note" before the
contents of a <code class="keyword markupname xmlelement">&lt;note&gt;</code> element.</p>
<section class="section">
<div class="p">The generated text extension point is used to add new strings to the default set of generated text. There are
several reasons you may want to use this:
<ul class="ul">
<li class="li">It can be used to add new text for your own processing extensions; for example, it could be used to add
localized versions of the string "User response" to aid in rendering troubleshooting information.</li>
<li class="li">It can be used to override the default strings in the toolkit; for example, it could be used to reset the
English string "Figure" to "Fig".</li>
<li class="li">It can be used to add support for new languages (for non-PDF transforms only; PDF requires more
complicated localization support). For example, it could be used to add support for Vietnamese or Gaelic; it
could also be used to support a new variant of a previously supported language, such as Australian
English.</li>
</ul></div>
<dl class="dl">
<dt class="dt dlterm"><code class="ph codeph">dita.xsl.strings</code></dt>
<dd class="dd">Add new strings to generated text file. </dd>
</dl>
</section>
<div class="example"><h2 class="title sectiontitle">Example: adding new strings</h2>
<p class="p">First, copy the file <span class="ph filepath">xsl/common/strings.xml</span> from the base plug-in directory
<span class="ph filepath">plugins/org.dita.base</span> to your plug-in, and edit it to contain the languages that you are
providing translations for ("en-US" must be present). For this sample, copy the file into your plug-in as
<span class="ph filepath">xsl/my-new-strings.xml</span>. The new strings file will look something like this:</p><pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;!-- Provide strings for my plug-in; this plug-in supports
English, Icelandic, and Russian. --&gt;
&lt;langlist&gt;
&lt;lang xml:lang="en" filename="mystring-en-us.xml"/&gt;
&lt;lang xml:lang="en-US" filename="mystring-en-us.xml"/&gt;
&lt;lang xml:lang="is" filename="mystring-is-is.xml"/&gt;
&lt;lang xml:lang="is-IS" filename="mystring-is-is.xml"/&gt;
&lt;lang xml:lang="ru" filename="mystring-ru-ru.xml"/&gt;
&lt;lang xml:lang="ru-RU" filename="mystring-ru-ru.xml"/&gt;
&lt;/langlist&gt;</code></pre>
<p class="p">Next, copy the file <span class="ph filepath">xsl/common/strings-en-us.xml</span> from the base plug-in directory
<span class="ph filepath">plugins/org.dita.base</span> to your plug-in, and replace the content with your own strings (be
sure to give them unique name attributes). Do the same for each language that you are providing a translation
for. For example, the file <span class="ph filepath">mystring-en-us.xml</span> might contain:</p><pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;strings xml:lang="en-US"&gt;
&lt;str name="String1"&gt;English generated text&lt;/str&gt;
&lt;str name="Another String"&gt;Another String in English&lt;/str&gt;
&lt;/strings&gt;</code></pre>
<p class="p">Use the following extension code to include your strings in the set of generated text: </p><pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;plugin id="com.example.strings"&gt;
&lt;feature extension="dita.xsl.strings" file="xsl/my-new-strings.xml"/&gt;
&lt;/plugin&gt;</code></pre>
<p class="p">The string is now available to the "getVariable" template used in many DITA-OT XSLT files. For example, if
processing in a context where the xml:lang value is "en-US", the following call would return "Another String in
English":</p><pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;xsl:call-template name="getVariable"&gt;
&lt;xsl:with-param name="id" select="'Another String'"/&gt;
&lt;/xsl:call-template&gt;</code></pre>
<div class="note note note_note"><span class="note__title">Note:</span> If two plug-ins define the same string, the results will be non-deterministic, so multiple plug-ins should
not try to create the same generated text string. One common way to avoid this problem is to ensure the name
attributes used to look up the string value are related to the ID or purpose of your plug-in.</div>
</div>
<div class="example"><h2 class="title sectiontitle">Example: modifying existing strings</h2>
<p class="p">The process for modifying existing generated text is exactly the same as for adding new text, except that the
strings you provide override values that already exist. To begin, set up the
<span class="ph filepath">xsl/my-new-strings.xml</span> file in your plug-in as in the previous example. </p>
<p class="p">Next, copy the file <span class="ph filepath">xsl/common/strings-en-us.xml</span> from the base plug-in directory
<span class="ph filepath">plugins/org.dita.base</span> to your plug-in, and choose the strings you wish to change (be sure
to leave the name attribute unchanged, because this is the key used to look up the string). Create a strings
file for each language that needs to modify existing strings. For example, the new file
<span class="ph filepath">mystring-en-us.xml</span> might contain:</p><pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;strings xml:lang="en-US"&gt;
&lt;str name="Figure"&gt;Fig&lt;/str&gt;
&lt;str name="Draft comment"&gt;ADDRESS THIS DRAFT COMMENT&lt;/str&gt;
&lt;/strings&gt;</code></pre>
<p class="p">To include the new strings, use the same method as above to add these strings to your
<span class="ph filepath">plugin.xml</span> file. Once this plug-in is installed, where XHTML output previously generated
the term "Figure", it will now generate "Fig"; where it previously generated "Draft comment", it will now
generate "ADDRESS THIS DRAFT COMMENT". The same strings in other languages will not be modified unless you also
provide new versions for those languages.</p><div class="note note note_note"><span class="note__title">Note:</span> If two plug-ins override the same string in the same
language, the results will be non-deterministic (either string may be used under different conditions). Multiple
plug-ins should not override the same generated text string for a single language.</div>
</div>
<div class="example"><h2 class="title sectiontitle">Example: adding a new language</h2>
<div class="p">The process for adding a new language is exactly the same as for adding new text, except you are effectively
just translating an existing strings file. To begin, set up the <span class="ph filepath">xsl/my-new-strings.xml</span> file
in your plug-in as in the previous examples. In this case, the only difference is that you are adding a mapping
to new languages; for example, the following file would be used to set up support for
Vietnamese:<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;!-- Map languages with xml:lang="vi" or xml:lang="vi-vn"
to the translations in this plug-in. --&gt;
&lt;langlist&gt;
&lt;lang xml:lang="vi" filename="strings-vi.xml"/&gt;
&lt;lang xml:lang="vi-VN" filename="strings-vi.xml"/&gt;
&lt;/langlist&gt;</code></pre></div>
<p class="p">Next, copy the file <span class="ph filepath">xsl/common/strings-en-us.xml</span> from the base plug-in directory
<span class="ph filepath">plugins/org.dita.base</span> to your plug-in, and rename it to match the language you wish to
add. For example, to support Vietnamese strings you may want to pick a name like
<span class="ph filepath">strings-vi.xml</span>. In that file, change the <code class="keyword markupname xmlatt">@xml:lang</code> attribute on the root
element to match your new language.</p>
<p class="p">Once the file is ready, translate the contents of each <code class="keyword markupname xmlelement">&lt;str&gt;</code> element (be sure to leave
the name attribute unchanged). Repeat this process for each new language you wish to add.</p>
<p class="p">To include the new languages, use the same method as above to add these strings to your
<span class="ph filepath">plugin.xml</span> file. Once this plug-in is installed, non-PDF builds will include support for
Vietnamese; instead of generating the English word "Caution", the element <code class="ph codeph">&lt;note type="caution"
xml:lang="vi"&gt;</code> may generate something like "<dfn class="term" lang="vi">chú ý</dfn>".</p><div class="note note note_note"><span class="note__title">Note:</span> If two
plug-ins add support for the same language using different values, the results will be non-deterministic
(translations from either plug-in may be picked up under different conditions).</div>
</div>
</div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/globalization.html" title="The DITA standard supports content that is written in or translated to any language. In general, DITA Open Toolkit passes content through to the output format unchanged. DITA-OT uses the values for the xml:lang and dir attributes that are set in the source content to provide globalization support. You can create custom plug-ins to support additional languages.">Globalizing DITA content</a></div></div><div class="linklist relref"><strong>Related reference</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/globalization-languages.html" title="The following languages are supported for all PDF, XHTML, and HTML5-based transformation types.">Languages supported by the core toolkit</a></li></ul></div></nav></article></main></body></html>

55
dita-ot-3.6/doc/topics/plugin-antpreprocess.html Normal file
View file

@ -0,0 +1,55 @@
<!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="You can add an Ant target to the pre-processing pipeline. This enables you to insert additional processing before or after the pre-processing chain or a specific step in the pre-processing operation."><meta name="keywords" content="plug-ins, Ant, Ant, preprocessing"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Adding an Ant target to the pre-processing pipeline</title></head><body id="plugin-antpreprocess"><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><ul><li><a href="../topics/plugin-set-parameters.html">Setting parameters</a></li><li><a href="../topics/plugin-anttarget.html">Adding a new Ant target</a></li><li class="active"><a href="../topics/plugin-antpreprocess.html">Adding a pre-processing step</a></li><li><a href="../topics/plugin-newtranstype.html">Adding a new output format</a></li><li><a href="../topics/plugin-xsltparams.html">Adding new parameters</a></li><li><a href="../topics/plugin-overridestyle.html">Overriding XSLT steps</a></li><li><a href="../topics/plugin-javalib.html">Adding a Java library</a></li><li><a href="../topics/plugin-messages.html">Adding new messages</a></li><li><a href="../topics/plugin-newextensions.html">New extension points</a></li><li><a href="../topics/plugin-xmlcatalog.html">Extending an XML catalog file</a></li><li><a href="../topics/plugin-rewrite-rules.html">Rewriting file names</a></li><li><a href="../topics/implement-saxon-customizations.html">Saxon customizations</a></li></ul></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></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">Adding an Ant target to the pre-processing pipeline</h1>
<div class="body taskbody"><p class="shortdesc">You can add an Ant target to the pre-processing pipeline. This enables you to insert additional processing
before or after the pre-processing chain or a specific step in the pre-processing operation.</p>
<section class="section context"><div class="tasklabel"><h2 class="sectiontitle tasklabel">About this task</h2></div>
<p class="p">You can use the <code class="ph codeph">depend.preprocess.pre</code> and <code class="ph codeph">depend.preprocess.post</code> extension
points to run a target before or after the entire pre-processing operation. In addition, there are extension
points that enable you to run an Ant target before specific pre-processing steps.</p>
<div class="note tip note_tip"><span class="note__title">Tip:</span> For maximum compatibility with future versions of
DITA-OT, most plug-ins should use the extension points that run <strong class="ph b">before</strong> or <strong class="ph b">after</strong>
pre-processing.</div>
</section>
<section><div class="tasklabel"><h2 class="sectiontitle tasklabel">Procedure</h2></div><ol class="ol steps"><li class="li step stepexpand">
<span class="ph cmd">Define and integrate the new Ant target.</span>
</li><li class="li step stepexpand">
<span class="ph cmd">Create the following <span class="ph filepath">plugin.xml</span> file:</span>
<div class="itemgroup info"><pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;plugin id="<var class="keyword varname">plugin-id</var>"&gt;
&lt;feature extension="<var class="keyword varname">extension-point</var>" value="<var class="keyword varname">Ant-target</var>"/&gt;
&lt;/plugin&gt;</code></pre>where
<ul class="ul">
<li class="li"><var class="keyword varname">plugin-id</var> is the plug-in identifier.</li>
<li class="li"><var class="keyword varname">extension-point</var> is a pre-processing extension point.</li>
<li class="li"><var class="keyword varname">Ant-target</var> is the name of the Ant target.</li>
</ul></div>
</li><li class="li step stepexpand">
<span class="ph cmd">Install the plug-in.</span>
</li></ol></section>
<section class="section result"><div class="tasklabel"><h2 class="sectiontitle tasklabel">Results</h2></div>The new target is added to the Ant dependency list. The new target is now always run in conjunction with the
specified step in the pre-processing pipeline.</section>
<section class="example"><h2 class="title sectiontitle">Example</h2>
<p class="p">The following <span class="ph filepath">plugin.xml</span> file specifies that the
<span class="keyword parmname">myAntTargetBeforeChunk</span> target is always run before the <code class="ph codeph">chunk</code> step in the
pre-processing stage.</p>
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;plugin id="com.example.extendchunk"&gt;
&lt;feature extension="depend.preprocess.chunk.pre"
value="myAntTargetBeforeChunk"/&gt;
&lt;/plugin&gt;</code></pre>
<p class="p">It assumes that the <span class="keyword parmname">myAntTargetBeforeChunk</span> target has already been defined and
integrated.</p>
<div class="note caution note_caution"><span class="note__title">CAUTION:</span> The internal order of preprocessing steps is
subject to change between versions of DITA-OT. New versions may remove, reorder, combine, or add steps to
the process, so the extension points <strong class="ph b">within</strong> the preprocessing stage should only be used if absolutely
necessary.</div>
</section>
</div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/plugin-use-cases.html" title="Plug-ins allow you to extend the functionality of DITA-OT. This might entail adding support for specialized document types, integrating processing overrides, or defining new output transformations.">Plug-in use cases</a></div></div><div class="linklist reltasks"><strong>Related tasks</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/plugins-installing.html" title="Use the dita install subcommand to install plug-ins.">Installing plug-ins</a></li></ul></div><div class="linklist relref"><strong>Related reference</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../extension-points/plugin-extension-points-pre-processing.html" title="You can use these extension points to run an Ant target before or after the pre-processing stage. If necessary, you can also run an Ant target before a specific pre-processing step — but this approach is not recommended.">Pre-processing extension points</a></li></ul></div></nav></article></main></body></html>

38
dita-ot-3.6/doc/topics/plugin-anttarget.html Normal file
View file

@ -0,0 +1,38 @@
<!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="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."><meta name="keywords" content="plug-ins, Ant, ant.import, preprocessing, Ant, targets"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Adding a new target to the Ant build process</title></head><body id="plugin-anttarget"><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><ul><li><a href="../topics/plugin-set-parameters.html">Setting parameters</a></li><li class="active"><a href="../topics/plugin-anttarget.html">Adding a new Ant target</a></li><li><a href="../topics/plugin-antpreprocess.html">Adding a pre-processing step</a></li><li><a href="../topics/plugin-newtranstype.html">Adding a new output format</a></li><li><a href="../topics/plugin-xsltparams.html">Adding new parameters</a></li><li><a href="../topics/plugin-overridestyle.html">Overriding XSLT steps</a></li><li><a href="../topics/plugin-javalib.html">Adding a Java library</a></li><li><a href="../topics/plugin-messages.html">Adding new messages</a></li><li><a href="../topics/plugin-newextensions.html">New extension points</a></li><li><a href="../topics/plugin-xmlcatalog.html">Extending an XML catalog file</a></li><li><a href="../topics/plugin-rewrite-rules.html">Rewriting file names</a></li><li><a href="../topics/implement-saxon-customizations.html">Saxon customizations</a></li></ul></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></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">Adding a new target to the Ant build process</h1>
<div class="body taskbody"><p class="shortdesc">As of DITA-OT 3.0, the <code class="ph codeph">ant.import</code> 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.</p>
<section><div class="tasklabel"><h2 class="sectiontitle tasklabel">Procedure</h2></div><ol class="ol steps"><li class="li step stepexpand">
<span class="ph cmd">Create an Ant project file that contains the new target(s).</span>
</li><li class="li step stepexpand">
<span class="ph cmd">Create the <span class="ph filepath">plugin.xml</span> file:</span>
<div class="itemgroup stepxmp"><pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;plugin id="<var class="keyword varname">plugin-id</var>"&gt;
&lt;feature extension="ant.import" file="<var class="keyword varname">build-file</var>"/&gt;
&lt;/plugin&gt;</code></pre>where:
<ul class="ul">
<li class="li"><var class="keyword varname">plugin-id</var> is the plug-in identifier, for example,
<code class="ph codeph">com.example.ant</code>.</li>
<li class="li"><var class="keyword varname">build-file</var> is the Ant project file that contains the new build target(s).</li>
</ul></div>
</li><li class="li step stepexpand">
<span class="ph cmd">Install the plug-in.</span>
</li></ol></section>
<section class="section result"><div class="tasklabel"><h2 class="sectiontitle tasklabel">Results</h2></div>
<p class="p">The targets from the project (<var class="keyword varname">build-file</var>) are copied into the <span class="ph filepath">build.xml</span>
file, using the correct path. This makes the new Ant targets available to other processes.</p>
<div class="note tip note_tip"><span class="note__title">Tip:</span> 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 described above should be used for all new
customizations.</div>
</section>
</div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/plugin-use-cases.html" title="Plug-ins allow you to extend the functionality of DITA-OT. This might entail adding support for specialized document types, integrating processing overrides, or defining new output transformations.">Plug-in use cases</a></div></div><div class="linklist reltasks"><strong>Related tasks</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/plugins-installing.html" title="Use the dita install subcommand to install plug-ins.">Installing plug-ins</a></li></ul></div><div class="linklist relref"><strong>Related reference</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../extension-points/plugin-extension-points-general.html" title="These extension points enable you to extend DITA-OT. You can add Ant targets or imports; add a Java library to the classpath parameter; add a new transformation type; extend a catalog file; add new diagnostic messages, and more.">General extension points</a></li></ul></div></nav></article></main></body></html>

26
dita-ot-3.6/doc/topics/plugin-benefits.html Normal file
View file

@ -0,0 +1,26 @@
<!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="Plug-ins allow you to extend the toolkit in a way that is consistent, easy-to-share, and possible to preserve through toolkit upgrades."><meta name="keywords" content="plug-ins, benefits"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Plug-in benefits</title></head><body id="plugin-benefits"><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 class="active"><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></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">Plug-in benefits</h1>
<div class="body conbody"><p class="shortdesc">Plug-ins allow you to extend the toolkit in a way that is consistent, easy-to-share, and possible to
preserve through toolkit upgrades.</p>
<p class="p">The DITA-OT plug-in mechanism provides the following benefits:</p>
<ul class="ul">
<li class="li">Plug-ins can easily be shared with other users, teams, or companies. Typically, all users need to do is to
unzip and run a single installation command. With many builds, even that installation step is automatic.</li>
<li class="li">Plug-ins permit overrides or customizations to grow from simple to complex over time, with no increased
complexity to the extension mechanism.</li>
<li class="li">Plug-ins can be moved from version to version of DITA-OT by reinstalling or copying the directory from one
installation to another. There is no need to re-integrate code based on updates to DITA-OT core processing.</li>
<li class="li">Plug-ins can build upon each other. If you like a plug-in, simply install that plug-in, and then create your
own plug-in that builds on top of it. The two plug-ins can then be distributed to your team as a unit, or you
can share your own extensions with the original provider.</li>
</ul>
</div>
<nav role="navigation" class="related-links"><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></nav></article></main></body></html>

206
dita-ot-3.6/doc/topics/plugin-coding-conventions.html Normal file
View file

File diff suppressed because one or more lines are too long

342
dita-ot-3.6/doc/topics/plugin-configfile.html Normal file
View file

@ -0,0 +1,342 @@
<!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="The plug-in descriptor file (plugin.xml) controls all aspects of a plug-in, making each extension visible to the rest of the toolkit. The file uses pre-defined extension points to locate changes, and then integrates those changes into the core DITA-OT code."><meta name="keywords" content="plug-ins, identfiers, plugin.xml, metadata, plug-in"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Plug-in descriptor file</title></head><body id="plugin-configfile"><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 class="active"><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></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">Plug-in descriptor file</h1>
<div class="body refbody"><p class="shortdesc">The plug-in descriptor file (<span class="ph filepath">plugin.xml</span>) controls all aspects of a plug-in, making
each extension visible to the rest of the toolkit. The file uses pre-defined extension points to locate changes, and
then integrates those changes into the core DITA-OT code.</p>
<section class="section"><h2 class="title sectiontitle">Validating plug-ins</h2>
<div class="div" id="plugin-configfile__d1181e92">
<p class="p">DITA-OT includes a RELAX&nbsp;NG schema file that can be used to validate the <span class="ph filepath">plugin.xml</span>
files that define the capabilities of each plug-in.
</p>
<p class="p">To ensure the syntax of your custom plug-in is correct, include an <code class="keyword markupname xmlpi">&lt;?xml-model?&gt;</code> processing
instruction at the beginning of the <span class="ph filepath">plugin.xml</span> file, immediately after the XML
prolog:</p>
<p class="p"><code class="keyword markupname xmlpi">&lt;?xml-model href="dita-ot/plugin.rnc" type="application/relax-ng-compact-syntax"?&gt;</code></p>
<p class="p">If your authoring environment does not apply this schema automatically, point your editor to <span class="ph filepath" id="plugin-configfile__d1181e123"><var class="keyword varname">dita-ot-dir</var>/resources/plugin.rnc</span> to associate the schema with
your plug-in file.</p>
</div>
</section>
<section class="section"><h2 class="title sectiontitle">Plug-in identifiers</h2>
<p class="p">Every DITA-OT plug-in must have a unique identifier composed of one or more dot-delimited tokens, for example,
<code class="ph codeph">com.example.rss</code>. This identifier is used to identify the plug-in to the toolkit for
installation, processing, and when determining plug-in dependencies.</p>
<div class="note note note_note"><span class="note__title">Note:</span> The default DITA-OT plug-ins use a reverse domain naming convention, as in <code class="ph codeph">org.dita.html5</code>;
this is strongly recommended to avoid plug-in naming conflicts.</div>
<div class="p" id="plugin-configfile__tokendef">Each token can include only the following characters:
<ul class="ul">
<li class="li">Lower-case letters (a-z)</li>
<li class="li">Upper-case letters (A-Z)</li>
<li class="li">Numerals (0-9)</li>
<li class="li">Underscores (_)</li>
<li class="li">Hyphens (-)</li>
</ul></div>
</section>
<section class="section"><h2 class="title sectiontitle"><code class="keyword markupname xmlelement">&lt;plugin&gt;</code></h2>
<p class="p">The root element of the <span class="ph filepath">plugin.xml</span> file is <code class="keyword markupname xmlelement">&lt;plugin&gt;</code>, which has a
required <code class="keyword markupname xmlatt">@id</code> attribute set to the unique plug-in identifier.</p>
<figure class="fig fignone"><figcaption><span class="fig--title-label">Figure 1. </span>Sample <code class="keyword markupname xmlelement">&lt;plugin&gt;</code> element</figcaption>
<pre class="pre codeblock language-xml"><code>&lt;plugin id="com.example.html5-javascript"&gt;</code></pre>
</figure>
</section>
<section class="section"><h2 class="title sectiontitle">Plug-in elements</h2>
<p class="p">The <code class="keyword markupname xmlelement">&lt;plugin&gt;</code> element can contain the following child elements: </p>
<dl class="dl parml">
<dt class="dt pt dlterm"><code class="keyword markupname xmlelement">&lt;extension-point&gt;</code></dt>
<dd class="dd pd">
<p class="p">An optional element that defines a new extension point that can be used by other DITA-OT plug-ins.</p>
<p class="p">The following attributes are supported:</p>
<table class="simpletable"><colgroup><col style="width:33.33333333333333%"><col style="width:33.33333333333333%"><col style="width:33.33333333333333%"></colgroup><thead><tr class="sthead">
<th class="stentry" scope="col" id="plugin-configfile__stentry__1">Attribute</th>
<th class="stentry" scope="col" id="plugin-configfile__stentry__2">Description</th>
<th class="stentry" scope="col" id="plugin-configfile__stentry__3">Required?</th>
</tr></thead><tbody><tr class="strow">
<th class="stentry" scope="row" headers="plugin-configfile__stentry__1">id</th>
<td class="stentry" headers="plugin-configfile__stentry__2">Extension point identifier</td>
<td class="stentry" headers="plugin-configfile__stentry__3">Yes</td>
</tr><tr class="strow">
<th class="stentry" scope="row" headers="plugin-configfile__stentry__1">name</th>
<td class="stentry" headers="plugin-configfile__stentry__2">Extension point description</td>
<td class="stentry" headers="plugin-configfile__stentry__3">No</td>
</tr></tbody></table>
<p class="p" id="plugin-configfile__extension-point-ids">Like plug-in identifiers, extension point identifiers are composed of one or
more dot-delimited tokens.</p>
<div class="note note note_note" id="plugin-configfile__entension-point-ids-note"><span class="note__title">Note:</span> Extension point identifiers should begin with the identifier of the
defining plug-in and append one or more tokens, for example, <code class="ph codeph">org.dita.example.pre</code>.</div>
<figure class="fig fignone"><figcaption><span class="fig--title-label">Figure 2. </span>Sample <code class="keyword markupname xmlelement">&lt;extension-point&gt;</code> element</figcaption>
<pre class="pre codeblock language-xml"><code>&lt;extension-point id="dita.xsl.html5" name="HTML5 XSLT import"/&gt;</code></pre>
</figure>
</dd>
<dt class="dt pt dlterm"><code class="keyword markupname xmlelement">&lt;feature&gt;</code></dt>
<dd class="dd pd">
<p class="p">An optional element that supplies values to a DITA-OT extension point.</p>
<p class="p">The following attributes are supported:</p>
<table class="simpletable"><colgroup><col style="width:33.33333333333333%"><col style="width:33.33333333333333%"><col style="width:33.33333333333333%"></colgroup><thead><tr class="sthead">
<th class="stentry" scope="col" id="plugin-configfile__stentry__10">Attribute</th>
<th class="stentry" scope="col" id="plugin-configfile__stentry__11">Description</th>
<th class="stentry" scope="col" id="plugin-configfile__stentry__12">Required?</th>
</tr></thead><tbody><tr class="strow">
<th class="stentry" scope="row" headers="plugin-configfile__stentry__10">extension</th>
<td class="stentry" headers="plugin-configfile__stentry__11">Identifier of the DITA-OT extension point</td>
<td class="stentry" headers="plugin-configfile__stentry__12">Yes</td>
</tr><tr class="strow">
<th class="stentry" scope="row" headers="plugin-configfile__stentry__10">value</th>
<td class="stentry" headers="plugin-configfile__stentry__11">Comma separated string value of the extension</td>
<td class="stentry" headers="plugin-configfile__stentry__12">Either the <code class="keyword markupname xmlatt">@value</code> or <code class="keyword markupname xmlatt">@file</code> attribute must be
specified</td>
</tr><tr class="strow">
<th class="stentry" scope="row" headers="plugin-configfile__stentry__10">file</th>
<td class="stentry" headers="plugin-configfile__stentry__11">Name and path of a file containing data for the extension point.
<p class="p">Depending on the extension point, this might be specified as an absolute path, a path relative to
the <span class="ph filepath">plugin.xml</span> file, or a path relative to the DITA-OT root.</p></td>
<td class="stentry" headers="plugin-configfile__stentry__12">Either the <code class="keyword markupname xmlatt">@value</code> or <code class="keyword markupname xmlatt">@file</code> attribute must be
specified</td>
</tr><tr class="strow">
<th class="stentry" scope="row" headers="plugin-configfile__stentry__10">type</th>
<td class="stentry" headers="plugin-configfile__stentry__11">Type of the <code class="keyword markupname xmlatt">@value</code> attribute</td>
<td class="stentry" headers="plugin-configfile__stentry__12">No</td>
</tr></tbody></table>
<figure class="fig fignone"><figcaption><span class="fig--title-label">Figure 3. </span>Sample <code class="keyword markupname xmlelement">&lt;feature&gt;</code> elements</figcaption>
<p class="p">If more than one <code class="keyword markupname xmlelement">&lt;feature&gt;</code> element supplies values to the same extension point,
the values are additive. For example, the following are equivalent:</p>
<pre class="pre codeblock language-xml"><code>&lt;feature extension="org.dita.example.extension-point" value="a,b,c"/&gt;</code></pre>
<pre class="pre codeblock language-xml"><code>&lt;feature extension="org.dita.example.extension-point" value="a"/&gt;
&lt;feature extension="org.dita.example.extension-point" value="b"/&gt;
&lt;feature extension="org.dita.example.extension-point" value="c"/&gt;</code></pre>
</figure>
</dd>
<dt class="dt pt dlterm"><code class="keyword markupname xmlelement">&lt;meta&gt;</code></dt>
<dd class="dd pd">
<p class="p">An optional element that defines metadata.</p>
<p class="p">The following attributes are supported:</p>
<table class="simpletable"><colgroup><col style="width:33.33333333333333%"><col style="width:33.33333333333333%"><col style="width:33.33333333333333%"></colgroup><thead><tr class="sthead">
<th class="stentry" scope="col" id="plugin-configfile__stentry__25">Attribute</th>
<th class="stentry" scope="col" id="plugin-configfile__stentry__26">Description</th>
<th class="stentry" scope="col" id="plugin-configfile__stentry__27">Required?</th>
</tr></thead><tbody><tr class="strow">
<th class="stentry" scope="row" headers="plugin-configfile__stentry__25">type</th>
<td class="stentry" headers="plugin-configfile__stentry__26">Metadata name </td>
<td class="stentry" headers="plugin-configfile__stentry__27">Yes</td>
</tr><tr class="strow">
<th class="stentry" scope="row" headers="plugin-configfile__stentry__25">value</th>
<td class="stentry" headers="plugin-configfile__stentry__26">Metadata value</td>
<td class="stentry" headers="plugin-configfile__stentry__27">Yes</td>
</tr></tbody></table>
<figure class="fig fignone"><figcaption><span class="fig--title-label">Figure 4. </span>Sample <code class="keyword markupname xmlelement">&lt;meta&gt;</code> element</figcaption>
<pre class="pre codeblock language-xml"><code>&lt;meta type="foo" value="bar"/&gt;</code></pre>
</figure>
</dd>
<dt class="dt pt dlterm"><code class="keyword markupname xmlelement">&lt;require&gt;</code></dt>
<dd class="dd pd">
<p class="p">An optional element that defines plug-in dependencies.</p>
<p class="p">The following attributes are supported:</p>
<table class="simpletable"><colgroup><col style="width:33.33333333333333%"><col style="width:33.33333333333333%"><col style="width:33.33333333333333%"></colgroup><thead><tr class="sthead">
<th class="stentry" scope="col" id="plugin-configfile__stentry__34">Attribute</th>
<th class="stentry" scope="col" id="plugin-configfile__stentry__35">Description</th>
<th class="stentry" scope="col" id="plugin-configfile__stentry__36">Required?</th>
</tr></thead><tbody><tr class="strow">
<th class="stentry" scope="row" headers="plugin-configfile__stentry__34">plugin</th>
<td class="stentry" headers="plugin-configfile__stentry__35">The identifier of the required plug-in.
<p class="p">To specify alternative requirements, separate plug-in identifiers with a vertical
bar.</p></td>
<td class="stentry" headers="plugin-configfile__stentry__36">Yes</td>
</tr><tr class="strow">
<th class="stentry" scope="row" headers="plugin-configfile__stentry__34">importance</th>
<td class="stentry" headers="plugin-configfile__stentry__35">Identifies whether the plug-in is <code class="ph codeph">required</code> (default) or
<code class="ph codeph">optional</code>. DITA-OT provides a warning if a required plug-in is not
available.</td>
<td class="stentry" headers="plugin-configfile__stentry__36">No</td>
</tr></tbody></table>
<figure class="fig fignone"><figcaption><span class="fig--title-label">Figure 5. </span>Sample <code class="keyword markupname xmlelement">&lt;require&gt;</code> element</figcaption>
<pre class="pre codeblock language-xml normalize-space"><code>&lt;require plugin="org.dita.html5"/&gt;</code></pre>
</figure>
</dd>
<dt class="dt pt dlterm"><code class="keyword markupname xmlelement">&lt;template&gt;</code></dt>
<dd class="dd pd">
<p class="p">An optional element that defines files that should be treated as templates.</p>
<p class="p">Template files can be used to integrate DITA-OT extensions. Templates typically extend the default
transformation-type-specific build files via <code class="keyword markupname xmlelement">&lt;dita:extension&gt;</code> elements. When the
plug-in installation process runs, template files are used to recreate build files, and the specified
extension points are replaced with references to the appropriate plug-ins.</p>
<p class="p">The following attributes are supported:</p>
<table class="simpletable"><colgroup><col style="width:33.33333333333333%"><col style="width:33.33333333333333%"><col style="width:33.33333333333333%"></colgroup><thead><tr class="sthead">
<th class="stentry" scope="col" id="plugin-configfile__stentry__43">Attribute</th>
<th class="stentry" scope="col" id="plugin-configfile__stentry__44">Description</th>
<th class="stentry" scope="col" id="plugin-configfile__stentry__45">Required?</th>
</tr></thead><tbody><tr class="strow">
<th class="stentry" scope="row" headers="plugin-configfile__stentry__43">file</th>
<td class="stentry" headers="plugin-configfile__stentry__44">Name and path to the template file, relative to the <span class="ph filepath">plugin.xml</span>
file</td>
<td class="stentry" headers="plugin-configfile__stentry__45">Yes</td>
</tr></tbody></table>
<figure class="fig fignone"><figcaption><span class="fig--title-label">Figure 6. </span>Sample <code class="keyword markupname xmlelement">&lt;template&gt;</code> element</figcaption>
<pre class="pre codeblock language-xml"><code>&lt;template file="build_dita2html5_template.xml"/&gt;</code></pre>
</figure>
</dd>
<dt class="dt pt dlterm"><code class="keyword markupname xmlelement">&lt;transtype&gt;</code></dt>
<dd class="dd pd">
<p class="p">An optional element that defines a new output format (transformation type).</p>
<p class="p">The following attributes are supported:</p>
<table class="simpletable"><colgroup><col style="width:33.33333333333333%"><col style="width:33.33333333333333%"><col style="width:33.33333333333333%"></colgroup><thead><tr class="sthead">
<th class="stentry" scope="col" id="plugin-configfile__stentry__49">Attribute</th>
<th class="stentry" scope="col" id="plugin-configfile__stentry__50">Description</th>
<th class="stentry" scope="col" id="plugin-configfile__stentry__51">Required?</th>
</tr></thead><tbody><tr class="strow">
<th class="stentry" scope="row" headers="plugin-configfile__stentry__49">name</th>
<td class="stentry" headers="plugin-configfile__stentry__50">Transformation name</td>
<td class="stentry" headers="plugin-configfile__stentry__51">Yes</td>
</tr><tr class="strow">
<th class="stentry" scope="row" headers="plugin-configfile__stentry__49">desc</th>
<td class="stentry" headers="plugin-configfile__stentry__50">Transformation type description</td>
<td class="stentry" headers="plugin-configfile__stentry__51">No</td>
</tr><tr class="strow">
<th class="stentry" scope="row" headers="plugin-configfile__stentry__49">abstract</th>
<td class="stentry" headers="plugin-configfile__stentry__50">When <span class="keyword option">true</span>, sets the transformation type as <q class="q">abstract</q>, meaning it can be
extended by other plug-ins, but cannot be used directly.
<p class="p">For example, the <code class="ph codeph">org.dita.base</code> plug-in defines an abstract <q class="q">base</q>
transformation type that is extended by other DITA-OT plug-ins.</p></td>
<td class="stentry" headers="plugin-configfile__stentry__51">No</td>
</tr><tr class="strow">
<th class="stentry" scope="row" headers="plugin-configfile__stentry__49">extends</th>
<td class="stentry" headers="plugin-configfile__stentry__50">Specifies the name of the transformation type being extended</td>
<td class="stentry" headers="plugin-configfile__stentry__51">No</td>
</tr></tbody></table>
<figure class="fig fignone"><figcaption><span class="fig--title-label">Figure 7. </span>Sample <code class="keyword markupname xmlelement">&lt;transtype&gt;</code> element</figcaption>
<pre class="pre codeblock language-xml"><code>&lt;transtype name="base" abstract="true" desc="Common"&gt;
&lt;!-- ⋮ --&gt;
&lt;param name="link-crawl"
desc="Specifies whether to crawl only topic links found in maps, or all discovered topic links."
type="enum"&gt;
&lt;val&gt;map&lt;/val&gt;
&lt;val default="true"&gt;topic&lt;/val&gt;
&lt;/param&gt;
&lt;!-- ⋮ --&gt;
&lt;/transtype&gt;
</code></pre>
</figure>
<p class="p">The <code class="keyword markupname xmlelement">&lt;transtype&gt;</code> element may define additional parameters for the transformation
type using the following child elements.</p>
<dl class="dl parml">
<dt class="dt pt dlterm"><code class="keyword markupname xmlelement">&lt;param&gt;</code></dt>
<dd class="dd pd">
<p class="p">An optional element that specifies a parameter for the transformation type.</p>
<p class="p">The following parameter attributes are supported:</p>
<table class="simpletable"><colgroup><col style="width:33.33333333333333%"><col style="width:33.33333333333333%"><col style="width:33.33333333333333%"></colgroup><thead><tr class="sthead">
<th class="stentry" scope="col" id="plugin-configfile__stentry__64">Attribute</th>
<th class="stentry" scope="col" id="plugin-configfile__stentry__65">Description</th>
<th class="stentry" scope="col" id="plugin-configfile__stentry__66">Required?</th>
</tr></thead><tbody><tr class="strow">
<th class="stentry" scope="row" headers="plugin-configfile__stentry__64">name</th>
<td class="stentry" headers="plugin-configfile__stentry__65">Parameter name</td>
<td class="stentry" headers="plugin-configfile__stentry__66">Yes</td>
</tr><tr class="strow">
<th class="stentry" scope="row" headers="plugin-configfile__stentry__64">desc</th>
<td class="stentry" headers="plugin-configfile__stentry__65">Parameter description</td>
<td class="stentry" headers="plugin-configfile__stentry__66">No</td>
</tr><tr class="strow">
<th class="stentry" scope="row" headers="plugin-configfile__stentry__64">type</th>
<td class="stentry" headers="plugin-configfile__stentry__65">Parameter type (<span class="keyword option">enum</span>, <span class="keyword option">file</span>,
<span class="keyword option">string</span>)</td>
<td class="stentry" headers="plugin-configfile__stentry__66">Yes</td>
</tr><tr class="strow">
<th class="stentry" scope="row" headers="plugin-configfile__stentry__64">deprecated</th>
<td class="stentry" headers="plugin-configfile__stentry__65">When <span class="keyword option">true</span>, identifies this parameter as deprecated</td>
<td class="stentry" headers="plugin-configfile__stentry__66">No</td>
</tr><tr class="strow">
<th class="stentry" scope="row" headers="plugin-configfile__stentry__64">required</th>
<td class="stentry" headers="plugin-configfile__stentry__65">When <span class="keyword option">true</span>, identifies this parameter as required</td>
<td class="stentry" headers="plugin-configfile__stentry__66">No</td>
</tr></tbody></table></dd>
<dt class="dt pt dlterm"><code class="keyword markupname xmlelement">&lt;val&gt;</code></dt>
<dd class="dd pd">
<p class="p">A child of <code class="keyword markupname xmlelement">&lt;param&gt;</code> (when <code class="keyword markupname xmlatt">@type</code>=<span class="keyword option">enum</span>) that
specifies an enumeration value.</p>
<p class="p">The following attributes are supported:</p>
<table class="simpletable"><colgroup><col style="width:33.33333333333333%"><col style="width:33.33333333333333%"><col style="width:33.33333333333333%"></colgroup><thead><tr class="sthead">
<th class="stentry" scope="col" id="plugin-configfile__stentry__82">Attribute</th>
<th class="stentry" scope="col" id="plugin-configfile__stentry__83">Description</th>
<th class="stentry" scope="col" id="plugin-configfile__stentry__84">Required?</th>
</tr></thead><tbody><tr class="strow">
<th class="stentry" scope="row" headers="plugin-configfile__stentry__82">default</th>
<td class="stentry" headers="plugin-configfile__stentry__83">When <span class="keyword option">true</span>, sets the enumeration value as the default value of the parent
<code class="keyword markupname xmlelement">&lt;param&gt;</code></td>
<td class="stentry" headers="plugin-configfile__stentry__84">Only for the default <code class="keyword markupname xmlelement">&lt;val&gt;</code></td>
</tr></tbody></table></dd>
</dl>
</dd>
</dl>
<p class="p">Any extension that is not recognized by DITA-OT is ignored. Since DITA-OT version 1.5.3, you can combine
multiple extension definitions within a single <span class="ph filepath">plugin.xml</span> file; in older versions, only the
last extension definition was used.</p>
</section>
<div class="example" id="plugin-configfile__plugin-sample"><h2 class="title sectiontitle">Example <span class="ph filepath">plugin.xml</span> file</h2>
<p class="p">The following is a sample of a <span class="ph filepath">plugin.xml</span> file. This file adds support for a new set of
specialized DTDs, and includes an override for the XHTML output processor.</p>
<p class="p">This <span class="ph filepath">plugin.xml</span> file would go into a directory such as
<span class="ph filepath">DITA-OT/plugins/music/</span> and referenced supporting files would also exist in that
directory. A more extensive sample using these values is available in the actual music plug-in, available on
<a class="xref" href="https://sourceforge.net/projects/dita-ot/files/Plug-in_%20Music/" target="_blank" rel="external noopener">SourceForge</a>.</p>
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;plugin id="org.metadita.specialization.music"&gt;
&lt;feature extension="dita.specialization.catalog.relative"
file="catalog-dita.xml"/&gt;
&lt;feature extension="dita.xsl.xhtml" file="xsl/music2xhtml.xsl"/&gt;
&lt;/plugin&gt;</code></pre>
</div>
</div>
<nav role="navigation" class="related-links"><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 reltasks"><strong>Related tasks</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/plugin-newtranstype.html" title="Plug-ins can add an entirely new transformation type. The new transformation type can be very simple, such as an HTML build that creates an additional control file; it also can be very complex, adding any number of new processing steps.">Adding a new transformation type</a></li></ul></div><div class="linklist relref"><strong>Related reference</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/plugin-newextensions.html" title="If your plug-in needs to define its own extension points in an XML file, add the string &#34;_template&#34; to the filename before the file suffix. When the plug-in is installed, this file will be processed like the built-in DITA-OT templates.">Creating a new plug-in extension point</a></li></ul></div></nav></article></main></body></html>

45
dita-ot-3.6/doc/topics/plugin-dependencies.html Normal file
View file

@ -0,0 +1,45 @@
<!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="A DITA-OT plug-in can be dependent on other plug-ins. Prerequisite plug-ins are installed first, which ensures that DITA-OT handles XSLT overrides correctly."><meta name="keywords" content=", require, plug-ins, prerequisites, dependencies, order, XSLT, plug-ins"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Plug-in dependencies</title></head><body id="plugin-dependencies"><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 class="active"><a href="../topics/plugin-dependencies.html">Plug-in dependencies</a><ul><li><a href="../topics/referencing-other-plugins.html">Referencing files from other plug-ins</a></li></ul></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></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">Plug-in dependencies</h1>
<div class="body conbody"><p class="shortdesc">A DITA-OT plug-in can be dependent on other plug-ins. Prerequisite plug-ins are installed first, which
ensures that DITA-OT handles XSLT overrides correctly.</p>
<section class="section">
<p class="p">The <code class="keyword markupname xmlelement">&lt;require&gt;</code> element in the <span class="ph filepath">plugin.xml</span> file specifies whether the
plug-in has dependencies. Use <code class="keyword markupname xmlelement">&lt;require&gt;</code> elements to specify prerequisite plug-ins, in
order from most general to most specific.</p>
<p class="p">If a prerequisite plug-in is missing, DITA-OT prints a warning during installation. To suppress the warning but
keep the installation order if both plug-ins are present, add <code class="ph codeph">importance="optional"</code> to the
<code class="keyword markupname xmlelement">&lt;require&gt;</code> element. </p>
<p class="p">If a plug-in can depend on any one of several optional plug-ins, separate the plug-in IDs with a vertical bar.
This is most useful when combined with <code class="ph codeph">importance="optional"</code>.</p>
</section>
<div class="example"><h2 class="title sectiontitle">Example: Plug-in with a prerequisite plug-in</h2>
<p class="p">The following plug-in will only be installed if the plug-in with the ID <code class="ph codeph">com.example.primary</code> is
available. If that plug-in is not available, a warning is generated and the installation operation fails.</p>
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;plugin id="com.example.builds-on-primary"&gt;
&lt;!-- ... Extensions here --&gt;
&lt;require plugin="com.example.primary"/&gt;
&lt;/plugin&gt;</code></pre>
</div>
<div class="example"><h2 class="title sectiontitle">Example: Plug-in that has optional plug-ins</h2>
<p class="p">The following plug-in will only be installed if either the plug-in with the ID <code class="ph codeph">pluginA</code> or the
plug-in with the ID <code class="ph codeph">pluginB</code> is available. If neither of those plug-ins are installed, a warning
is generated but the installation operation is completed.</p>
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;plugin id="pluginC"&gt;
&lt;!-- ...extensions here --&gt;
&lt;require plugin="pluginA|pluginB" importance="optional"/&gt;
&lt;/plugin&gt;</code></pre>
</div>
</div>
<nav role="navigation" class="related-links"><ul class="ullinks"><li class="link ulchildlink"><strong><a href="../topics/referencing-other-plugins.html">Referencing files from other plug-ins</a></strong><br>Starting with DITA-OT 1.5.4, you can use the <span class="ph filepath">plugin:<var class="keyword varname">plugin-id</var></span> URI extension and the <span class="ph filepath">${dita.plugin.<var class="keyword varname">plugin-id</var>.dir}</span> Ant variable to reference the base path of another installed DITA-OT plug-in.</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 relconcepts"><strong>Related concepts</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/plugin-coding-conventions.html" title="To ensure custom plug-ins work well with the core toolkit code and remain compatible with future releases, the DITA Open Toolkit project recommends that plug-ins use modern development practices and common coding patterns.">Plug-in coding conventions</a></li></ul></div></nav></article></main></body></html>

78
dita-ot-3.6/doc/topics/plugin-javalib.html Normal file
View file

@ -0,0 +1,78 @@
<!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="You can use the dita.conductor.lib.import extension point to add an additional Java library to the DITA-OT classpath parameter."><meta name="keywords" content="deprecated features, property, dost.class.path, plug-ins, Java, Java, classpath, classpath, XSLT"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Adding a Java library to the classpath</title></head><body id="plugin-javalib"><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><ul><li><a href="../topics/plugin-set-parameters.html">Setting parameters</a></li><li><a href="../topics/plugin-anttarget.html">Adding a new Ant target</a></li><li><a href="../topics/plugin-antpreprocess.html">Adding a pre-processing step</a></li><li><a href="../topics/plugin-newtranstype.html">Adding a new output format</a></li><li><a href="../topics/plugin-xsltparams.html">Adding new parameters</a></li><li><a href="../topics/plugin-overridestyle.html">Overriding XSLT steps</a></li><li class="active"><a href="../topics/plugin-javalib.html">Adding a Java library</a></li><li><a href="../topics/plugin-messages.html">Adding new messages</a></li><li><a href="../topics/plugin-newextensions.html">New extension points</a></li><li><a href="../topics/plugin-xmlcatalog.html">Extending an XML catalog file</a></li><li><a href="../topics/plugin-rewrite-rules.html">Rewriting file names</a></li><li><a href="../topics/implement-saxon-customizations.html">Saxon customizations</a></li></ul></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></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">Adding a Java library to the <span class="keyword parmname">classpath</span></h1>
<div class="body taskbody"><p class="shortdesc">You can use the <code class="ph codeph">dita.conductor.lib.import</code> extension point to add an additional Java
library to the DITA-OT <span class="keyword parmname">classpath</span> parameter.</p>
<section class="section context"><div class="tasklabel"><h2 class="sectiontitle tasklabel">About this task</h2></div>
<p class="p">As of DITA-OT 3.1, the Java class path is managed automatically, meaning you do not (and should not) use
explicit references to Java class paths in your build scripts. In particular, the old
<code class="ph codeph">dost.class.path</code> property has been deprecated and should not be used. If you are migrating
older plug-ins that manage their class path directly, you should remove any explicit class path configuration.
If your plug-in was not already using the <code class="ph codeph">dita.conductor.lib.import</code> extension point to
integrate its JAR dependencies you must add it.</p>
<p class="p">The effective DITA-OT class path is the combination of the JAR files in the main <span class="ph filepath">lib/</span>
directory and the plug-in-contributed JARs, which are listed in <span class="ph filepath">config/env.sh</span>. The
<span class="ph filepath">env.sh</span> file is updated automatically when plug-ins are installed or removed.</p>
</section>
<section><div class="tasklabel"><h2 class="sectiontitle tasklabel">Procedure</h2></div><ol class="ol steps"><li class="li step stepexpand">
<span class="ph cmd">If necessary, compile the Java code into a JAR file.</span>
</li><li class="li step stepexpand">
<span class="ph cmd">Create a <span class="ph filepath">plugin.xml</span> file that contains the following code:</span>
<div class="itemgroup info"><pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;plugin id="<var class="keyword varname">plugin-id</var>"&gt;
&lt;feature extension="dita.conductor.lib.import" file="<var class="keyword varname">file</var>"/&gt;
&lt;/plugin&gt;</code></pre>where:
<ul class="ul">
<li class="li"><var class="keyword varname">plugin-id</var> is the plug-in identifier, for example,
<code class="ph codeph">com.example.addjar</code>.</li>
<li class="li"><var class="keyword varname">file</var> is the name of the JAR file, for example,
<span class="ph filepath">myJavaLibrary.jar</span>. </li>
</ul></div>
</li><li class="li step stepexpand">
<span class="ph cmd">Install the plug-in.</span>
</li></ol></section>
<section class="section result"><div class="tasklabel"><h2 class="sectiontitle tasklabel">Results</h2></div>The Ant or XSLT code now can make use of the Java code.</section>
<section class="example"><div class="tasklabel"><h2 class="sectiontitle tasklabel">Example</h2></div>
<p class="p">In the following extended example, the <span class="ph filepath">myJavaLibrary.jar</span> file performs a validation step
during processing, and you want it to run immediately before the <code class="ph codeph">conref </code>step.</p>
<p class="p">To accomplish this, you will need to use several features:</p>
<ul class="ul">
<li class="li">The JAR file must be added to the classpath.</li>
<li class="li">The Ant target must be added to the dependency chain for conref.</li>
<li class="li">An Ant target must be created that uses this class, and integrated into the code.</li>
</ul>
<p class="p">The files might look like the following:</p>
<figure class="fig fignone"><figcaption><span class="fig--title-label">Figure 1. </span><span class="ph filepath">plugin.xml</span> file</figcaption>
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;plugin id="com.example.samplejava"&gt;
<em class="ph i">&lt;!-- Add the JAR file to the DITA-OT CLASSPATH --&gt;</em>
<strong class="ph b">&lt;feature extension="dita.conductor.lib.import"
file="com.example.sampleValidation.jar"/&gt;</strong>
<em class="ph i">&lt;!-- Integrate the Ant code --&gt;</em>
&lt;feature extension="ant.import" file="calljava-antcode.xml"/&gt;
<em class="ph i">&lt;!-- Define the Ant target to call, and when (before conref) --&gt;</em>
&lt;feature extension="depend.preprocess.conref.pre"
value="validateWithJava"/&gt;
&lt;/plugin&gt;</code></pre>
</figure>
<figure class="fig fignone"><figcaption><span class="fig--title-label">Figure 2. </span><span class="ph filepath">calljava-antcode.xml</span> file</figcaption>
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;project default="validateWithJava"&gt;
&lt;target name="validateWithJava"&gt;
&lt;java classname="com.example.sampleValidation"&gt;
&lt;!-- The class was added to the DITA-OT classpath --&gt;
&lt;/java&gt;
&lt;/target&gt;
&lt;/project&gt;</code></pre>
</figure>
</section>
</div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/plugin-use-cases.html" title="Plug-ins allow you to extend the functionality of DITA-OT. This might entail adding support for specialized document types, integrating processing overrides, or defining new output transformations.">Plug-in use cases</a></div></div><div class="linklist reltasks"><strong>Related tasks</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/plugins-installing.html" title="Use the dita install subcommand to install plug-ins.">Installing plug-ins</a></li></ul></div><div class="linklist relref"><strong>Related reference</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../extension-points/plugin-extension-points-general.html" title="These extension points enable you to extend DITA-OT. You can add Ant targets or imports; add a Java library to the classpath parameter; add a new transformation type; extend a catalog file; add new diagnostic messages, and more.">General extension points</a></li></ul></div></nav></article></main></body></html>

86
dita-ot-3.6/doc/topics/plugin-messages.html Normal file
View file

@ -0,0 +1,86 @@
<!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="Use the dita.xsl.messages extension point to add plug-in-specific messages to the diagnostic messages that are generated by DITA-OT. These messages then can be used by any XSLT override."><meta name="keywords" content=", type, , id, diagnostic messages, plug-ins, troubleshooting, troubleshooting, plug-ins, XSLT, errors, preprocessing, XSLT"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Adding new diagnostic messages</title></head><body id="plugin-messages"><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><ul><li><a href="../topics/plugin-set-parameters.html">Setting parameters</a></li><li><a href="../topics/plugin-anttarget.html">Adding a new Ant target</a></li><li><a href="../topics/plugin-antpreprocess.html">Adding a pre-processing step</a></li><li><a href="../topics/plugin-newtranstype.html">Adding a new output format</a></li><li><a href="../topics/plugin-xsltparams.html">Adding new parameters</a></li><li><a href="../topics/plugin-overridestyle.html">Overriding XSLT steps</a></li><li><a href="../topics/plugin-javalib.html">Adding a Java library</a></li><li class="active"><a href="../topics/plugin-messages.html">Adding new messages</a></li><li><a href="../topics/plugin-newextensions.html">New extension points</a></li><li><a href="../topics/plugin-xmlcatalog.html">Extending an XML catalog file</a></li><li><a href="../topics/plugin-rewrite-rules.html">Rewriting file names</a></li><li><a href="../topics/implement-saxon-customizations.html">Saxon customizations</a></li></ul></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></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">Adding new diagnostic messages</h1>
<div class="body taskbody"><p class="shortdesc">Use the <code class="ph codeph">dita.xsl.messages</code> extension point to add plug-in-specific messages to the
diagnostic messages that are generated by DITA-OT. These messages then can be used by any XSLT override.</p>
<section><div class="tasklabel"><h2 class="sectiontitle tasklabel">Procedure</h2></div><ol class="ol steps"><li class="li step stepexpand" id="plugin-messages__step_create-message-xml">
<span class="ph cmd">Create an XML file that contains the messages that you want to add. Be sure to use the following format for
the XML file:</span>
<div class="itemgroup info"><pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;messages&gt;
<em class="ph i">&lt;!-- See resources/messages.xml for the details. --&gt;</em>
&lt;message id="<var class="keyword varname">Prefix</var><var class="keyword varname">Number</var><var class="keyword varname">Letter</var>" type="<var class="keyword varname">error-severity</var>"&gt;
&lt;reason&gt;Message text&lt;/reason&gt;
&lt;response&gt;How to resolve&lt;/response&gt;
&lt;/message&gt;
&lt;/messages&gt;</code></pre>where:
<ul class="ul">
<li class="li"><var class="keyword varname">Prefix</var> is a sequence of four capital letters.<div class="note note note_note"><span class="note__title">Note:</span> By convention, the toolkit
messages use <code class="ph codeph">DOTX</code> but any sequence can be used by plug-in developers.</div></li>
<li class="li"><var class="keyword varname">Number</var> is a three-digit integer.</li>
<li class="li"><var class="keyword varname">Letter</var> is one of the following upper-case letters: I, W, E, F. It should match the
value that is specified for the <code class="keyword markupname xmlatt">@type</code> attribute.<div class="note note note_note"><span class="note__title">Note:</span> As the <code class="keyword markupname xmlatt">@id</code> attribute
is used as a whole and not decomposed by recent versions of the toolkit, you could use any sequence as
the message identifier. Nevertheless, to facilitate reuse of the plug-in and make it more readable by
other users, we recommend following these guidelines.</div></li>
<li class="li"><var class="keyword varname">error-severity</var> specifies the severity of the error. It must be one of the following
values:
<dl class="dl">
<dt class="dt dlterm">Info (I)</dt>
<dd class="dd">Informational messages highlight the progress of transformation and call attention to conditions of which
you should be aware. For example, draft comments are enabled and will be rendered in the output.</dd>
<dt class="dt dlterm">Warning (W)</dt>
<dd class="dd">The toolkit encountered a problem that should be corrected. Processing will continue, but the output might
not be as expected.</dd>
<dt class="dt dlterm">Error (E)</dt>
<dd class="dd">The toolkit encountered a more severe problem, and the output is affected. For example, some content is
missing or invalid, or the content is not rendered in the output</dd>
<dt class="dt dlterm">Fatal (F)</dt>
<dd class="dd">The toolkit encountered a severe condition, processing stopped, and no output is generated.</dd>
</dl><div class="note note note_note"><span class="note__title">Note:</span> The <code class="ph codeph">FATAL</code> value throws a fatal error message in XSLT and an exception in
Java.</div>
<div class="note tip note_tip"><span class="note__title">Tip:</span> If the <code class="keyword markupname xmlatt">@id</code> attribute of your message is equal to the <code class="keyword markupname xmlatt">@id</code>
of a default DITA-OT message, your message will override the default one.</div></li>
</ul></div>
</li><li class="li step stepexpand">
<span class="ph cmd">Create a <span class="ph filepath">plugin.xml</span> file that contains the following content:</span>
<div class="itemgroup info">
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;plugin id="<var class="keyword varname">plugin-id</var>"&gt;
&lt;feature extension="dita.xsl.messages" file="<var class="keyword varname">file</var>"/&gt;
&lt;/plugin&gt;</code></pre>
<p class="p">where:</p>
<ul class="ul">
<li class="li"><var class="keyword varname">plugin-id</var> is the plug-in identifier, for example,
<code class="ph codeph">com.example.newmsg</code>.</li>
<li class="li"><var class="keyword varname">file</var> is the name of the new XML file containing the messages created in step
<a class="xref" href="plugin-messages.html#plugin-messages__step_create-message-xml">1</a>, for example,
<span class="ph filepath">myMessages.xml</span>. </li>
</ul>
</div>
</li><li class="li step stepexpand">
<span class="ph cmd">Install the plug-in.</span>
</li></ol></section>
<section class="section postreq"><div class="tasklabel"><h2 class="sectiontitle tasklabel">What to do next</h2></div>
<p class="p">Add the following call in XSLT modules to generate a message when a specific condition occurs:</p>
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;xsl:call-template name="output-message"&gt;
&lt;xsl:with-param name="id"&gt;<var class="keyword varname">prefix</var><var class="keyword varname">number</var><var class="keyword varname">letter</var>&lt;/xsl:with-param&gt;
&lt;xsl:with-param name="msg"&gt;Message text and parameters.&lt;/xsl:with-param&gt;
&lt;/xsl:call-template&gt;</code></pre>
<p class="p">Use the <code class="ph codeph">ctx</code> parameter if calling from a function.</p>
</section>
</div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/plugin-use-cases.html" title="Plug-ins allow you to extend the functionality of DITA-OT. This might entail adding support for specialized document types, integrating processing overrides, or defining new output transformations.">Plug-in use cases</a></div></div><div class="linklist reltasks"><strong>Related tasks</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/plugins-installing.html" title="Use the dita install subcommand to install plug-ins.">Installing plug-ins</a></li></ul></div><div class="linklist relref"><strong>Related reference</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../extension-points/plugin-extension-points-general.html" title="These extension points enable you to extend DITA-OT. You can add Ant targets or imports; add a Java library to the classpath parameter; add a new transformation type; extend a catalog file; add new diagnostic messages, and more.">General extension points</a></li></ul></div></nav></article></main></body></html>

132
dita-ot-3.6/doc/topics/plugin-newextensions.html Normal file
View file

@ -0,0 +1,132 @@
<!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 your plug-in needs to define its own extension points in an XML file, add the string &#34;_template&#34; to the filename before the file suffix. When the plug-in is installed, this file will be processed like the built-in DITA-OT templates."><meta name="keywords" content=", template, dita:extension, pathelement, xsl:import, , id, plug-in, behavior, plug-ins, extension points, extension points, creating, XSLT, preprocessing, XSLT, metadata, catalog"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Creating a new plug-in extension point</title></head><body id="plugin-newextensions"><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><ul><li><a href="../topics/plugin-set-parameters.html">Setting parameters</a></li><li><a href="../topics/plugin-anttarget.html">Adding a new Ant target</a></li><li><a href="../topics/plugin-antpreprocess.html">Adding a pre-processing step</a></li><li><a href="../topics/plugin-newtranstype.html">Adding a new output format</a></li><li><a href="../topics/plugin-xsltparams.html">Adding new parameters</a></li><li><a href="../topics/plugin-overridestyle.html">Overriding XSLT steps</a></li><li><a href="../topics/plugin-javalib.html">Adding a Java library</a></li><li><a href="../topics/plugin-messages.html">Adding new messages</a></li><li class="active"><a href="../topics/plugin-newextensions.html">New extension points</a></li><li><a href="../topics/plugin-xmlcatalog.html">Extending an XML catalog file</a></li><li><a href="../topics/plugin-rewrite-rules.html">Rewriting file names</a></li><li><a href="../topics/implement-saxon-customizations.html">Saxon customizations</a></li></ul></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></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">Creating a new plug-in extension point</h1>
<div class="body refbody"><p class="shortdesc">If your plug-in needs to define its own extension points in an XML file, add the string
"<code class="ph codeph">_template</code>" to the filename before the file suffix. When the plug-in is installed, this file will
be processed like the built-in DITA-OT templates.</p>
<section class="section">
<p class="p">Template files are used to integrate most DITA-OT extensions. For example, the
<span class="ph filepath">dita2xhtml_template.xsl</span> file contains all of the default rules for converting DITA topics
to XHTML, along with an extension point for plug-in extensions. When the plug-in is installed, the
<span class="ph filepath">dita2xhtml.xsl</span> is recreated, and the extension point is replaced with references to all
appropriate plug-ins.</p>
<p class="p">To mark a new file as a template file, use the <code class="keyword markupname xmlelement">&lt;template&gt;</code> element.</p>
<p class="p">The template extension namespace has the URI <code class="ph codeph">http://dita-ot.sourceforge.net</code>. It is used to
identify elements and attributes that have a special meaning in template processing. This documentation uses the
<code class="ph codeph">dita:</code> prefix to refer to elements in the template extension namespace. However, template
files are free to use any prefix, provided that there is a namespace declaration that binds the prefix to the
URI of the template extension namespace. </p>
</section>
<section class="section"><h2 class="title sectiontitle"><code class="keyword markupname xmlelement">&lt;dita:extension&gt;</code> element</h2>
<p class="p">The <code class="keyword markupname xmlelement">&lt;dita:extension&gt;</code> elements are used to insert generated content during the plug-in
installation process. There are two required attributes:</p>
<ul class="ul">
<li class="li">The <code class="keyword markupname xmlatt">@id</code> attribute defines the extension point ID that provides the argument data.</li>
<li class="li">The <code class="keyword markupname xmlatt">@behavior</code> attribute defines which processing action is used.</li>
</ul>
<p class="p">Supported values for the <code class="keyword markupname xmlatt">@behavior</code> attribute:</p>
<dl class="dl parml">
<dt class="dt pt dlterm"><code class="ph codeph">org.dita.dost.platform.CheckTranstypeAction</code></dt>
<dd class="dd pd">Create Ant condition elements to check if the <code class="ph codeph">${transtype}</code> property value equals a
supported transformation type value.</dd>
<dt class="dt pt dlterm"><code class="ph codeph">org.dita.dost.platform.ImportAntLibAction</code></dt>
<dd class="dd pd">Create Ant <code class="keyword markupname xmlelement">&lt;pathelement&gt;</code> elements for the
<a class="xref" href="plugin-javalib.html" title="You can use the dita.conductor.lib.import extension point to add an additional Java library to the DITA-OT classpath parameter.">library import extension point</a>. The <code class="keyword markupname xmlatt">@id</code> attribute is
used to define the extension point ID.</dd>
<dt class="dt pt dlterm"><code class="ph codeph">org.dita.dost.platform.ImportPluginCatalogAction</code></dt>
<dd class="dd pd">Include plug-in metadata catalog content.</dd>
<dt class="dt pt dlterm"><code class="ph codeph">org.dita.dost.platform.ImportPluginInfoAction</code></dt>
<dd class="dd pd">Create plug-in metadata Ant properties.</dd>
<dt class="dt pt dlterm"><code class="ph codeph">org.dita.dost.platform.ImportStringsAction</code></dt>
<dd class="dd pd">Include plug-in string file content based on the
<a class="xref" href="plugin-addgeneratedtext.html" title="Generated text is the term for strings that are automatically added by the build, such as &#34;Note&#34; before the contents of a note element.">generated text extension point</a>. The <code class="keyword markupname xmlatt">@id</code>
attribute is used to define the extension point ID.</dd>
<dt class="dt pt dlterm"><code class="ph codeph">org.dita.dost.platform.ImportXSLAction</code></dt>
<dd class="dd pd">Create <code class="keyword markupname xmlelement">&lt;xsl:import&gt;</code> elements based on the
<a class="xref" href="plugin-overridestyle.html" title="You can override specific XSLT-processing steps in both the pre-processing pipeline and certain DITA-OT transformations.">XSLT import extension point</a>. The <code class="keyword markupname xmlatt">@id</code> attribute is
used to define the extension point ID.</dd>
<dt class="dt pt dlterm"><code class="ph codeph">org.dita.dost.platform.InsertAction</code></dt>
<dd class="dd pd">Include plug-in conductor content based on the
<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.">Ant import extension point</a>. The <code class="keyword markupname xmlatt">@id</code> attribute is used
to define the extension point ID.</dd>
<dt class="dt pt dlterm"><code class="ph codeph">org.dita.dost.platform.InsertAntActionRelative</code></dt>
<dd class="dd pd">Include plug-in conductor content based on the
<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.">relative Ant import extension point</a>. The <code class="keyword markupname xmlatt">@id</code>
attribute is used to define the extension point ID.</dd>
<dt class="dt pt dlterm"><code class="ph codeph">org.dita.dost.platform.InsertCatalogActionRelative</code></dt>
<dd class="dd pd">Include plug-in catalog content based on the
<a class="xref" href="plugin-xmlcatalog.html" title="You can update either the main DITA-OT XML catalog or the XML catalog that is used by the PDF plug-in. This enables DITA-OT to support new specializations and document-type shells.">catalog import extension point</a>. The <code class="keyword markupname xmlatt">@id</code> attribute is
used to define the extension point ID.</dd>
<dt class="dt pt dlterm"><code class="ph codeph">org.dita.dost.platform.ListTranstypeAction</code></dt>
<dd class="dd pd">Create a pipe-delimited list of supported transformation types.</dd>
</dl>
</section>
<section class="section" id="plugin-newextensions__section_vfc_gvw_mg"><h2 class="title sectiontitle"><code class="keyword markupname xmlatt">@dita:extension</code> attribute</h2>
<p class="p">The <code class="keyword markupname xmlatt">@dita:extension</code> attribute is used to process attributes in elements which are not in the
template extension namespace. The value of the attribute is a space-delimited tuple, where the first item is the
name of the attribute to process and the second item is the action ID.</p>
<p class="p">Supported values:</p>
<dl class="dl parml">
<dt class="dt pt dlterm"><code class="ph codeph">depends org.dita.dost.platform.InsertDependsAction</code></dt>
<dd class="dd pd">The Ant target dependency list is processed to replace all target names that start with an opening brace
<code class="ph codeph">{</code> character and end with a closing brace <code class="ph codeph">}</code>. The value of the extension
point is the ID between the braces.</dd>
</dl>
</section>
<div class="example"><h2 class="title sectiontitle">Example</h2>
<p class="p">The following plug-in defines <span class="ph filepath">myBuildFile_template.xml</span> as a new template for extensions,
and two new extension points.</p>
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;plugin id="com.example.new-extensions"&gt;
&lt;extension-point id="com.example.new-extensions.pre"
name="Custom target preprocess"/&gt;
&lt;extension-point id="com.example.new-extensions.content"
name="Custom target content"/&gt;
&lt;template file="myBuildFile_template.xml"/&gt;
&lt;/plugin&gt;</code></pre>
<p class="p">When the plug-in is installed, this will be used to recreate <span class="ph filepath">myBuildFile.xml</span>, replacing
Ant file content based on extension point use.</p>
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;project xmlns:dita="http://dita-ot.sourceforge.net"&gt;
&lt;target name="dita2custom"
dita:depends="dita2custom.init,
{com.example.new-extensions.pre},
dita2xhtml"
dita:extension="depends org.dita.dost.platform.InsertDependsAction"&gt;
&lt;dita:extension id="com.example.new-extensions.content"
behavior="org.dita.dost.platform.InsertAction"/&gt;
&lt;/target&gt;
&lt;/project&gt;</code></pre>
</div>
</div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/plugin-use-cases.html" title="Plug-ins allow you to extend the functionality of DITA-OT. This might entail adding support for specialized document types, integrating processing overrides, or defining new output transformations.">Plug-in use cases</a></div></div></nav></article></main></body></html>

85
dita-ot-3.6/doc/topics/plugin-newtranstype.html Normal file
View file

@ -0,0 +1,85 @@
<!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="Plug-ins can add an entirely new transformation type. The new transformation type can be very simple, such as an HTML build that creates an additional control file; it also can be very complex, adding any number of new processing steps."><meta name="keywords" content=", transtype, custom, param, plug-ins, transformations, transformations, creating, table of contents, HTML5"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Adding a new transformation type</title></head><body id="plugin-newtranstype"><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><ul><li><a href="../topics/plugin-set-parameters.html">Setting parameters</a></li><li><a href="../topics/plugin-anttarget.html">Adding a new Ant target</a></li><li><a href="../topics/plugin-antpreprocess.html">Adding a pre-processing step</a></li><li class="active"><a href="../topics/plugin-newtranstype.html">Adding a new output format</a></li><li><a href="../topics/plugin-xsltparams.html">Adding new parameters</a></li><li><a href="../topics/plugin-overridestyle.html">Overriding XSLT steps</a></li><li><a href="../topics/plugin-javalib.html">Adding a Java library</a></li><li><a href="../topics/plugin-messages.html">Adding new messages</a></li><li><a href="../topics/plugin-newextensions.html">New extension points</a></li><li><a href="../topics/plugin-xmlcatalog.html">Extending an XML catalog file</a></li><li><a href="../topics/plugin-rewrite-rules.html">Rewriting file names</a></li><li><a href="../topics/implement-saxon-customizations.html">Saxon customizations</a></li></ul></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></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">Adding a new transformation type</h1>
<div class="body taskbody"><p class="shortdesc">Plug-ins can add an entirely new transformation type. The new transformation type can be very simple, such
as an HTML build that creates an additional control file; it also can be very complex, adding any number of new
processing steps.</p>
<section class="section context"><div class="tasklabel"><h2 class="sectiontitle tasklabel">About this task</h2></div>
<p class="p">You can use the <code class="keyword markupname xmlelement">&lt;transtype&gt;</code> element to define a new transformation type with any new
custom parameters that are supported.</p>
<p class="p">When a transformation type is defined, the build expects Ant code to be integrated to define the transformation
process. The Ant code must define a target based on the name of the transformation type; if the transformation
type is "new-transform", the Ant code must define a target named <span class="keyword parmname">dita2new-transform</span>.</p>
</section>
<section><div class="tasklabel"><h2 class="sectiontitle tasklabel">Procedure</h2></div><ol class="ol steps"><li class="li step stepexpand">
<span class="ph cmd">Create an Ant project file for the new transformation. This project file must define a target named
"dita2<var class="keyword varname">new-transtype</var>," where <var class="keyword varname">new-transtype</var> is the name of the new
transformation type. </span>
</li><li class="li step stepexpand">
<span class="ph cmd">Create a <span class="ph filepath">plugin.xml</span> with the following content:</span>
<div class="itemgroup info">
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;plugin id="<var class="keyword varname">plugin-id</var>"&gt;
&lt;transtype name="<var class="keyword varname">new-transtype</var>"/&gt;
<strong class="ph b">&lt;feature extension="dita.transtype.print" value="<var class="keyword varname">new-transtype</var>"/&gt;</strong>
&lt;feature extension="ant.import" file="<var class="keyword varname">ant-file</var>"/&gt;
&lt;/plugin&gt;</code></pre>
<p class="p">where:</p>
<ul class="ul">
<li class="li"><var class="keyword varname">plugin-id </var> is the plug-in identifier, for example, com.dita-ot.pdf.</li>
<li class="li"><var class="keyword varname">new-transtype</var> is the name of the new transformation, for example, dita-ot-pdf.</li>
<li class="li"><var class="keyword varname">ant-file</var> is the name of the Ant file, for example,
<span class="ph filepath">build-dita-ot-pdf.xml</span>.</li>
</ul>
<p class="p">Exclude the content that is highlighted in bold if the transformation is not intended for print.</p>
</div>
</li><li class="li step stepexpand">
<span class="ph cmd">Install the plug-in.</span>
</li></ol></section>
<section class="section result"><div class="tasklabel"><h2 class="sectiontitle tasklabel">Results</h2></div>You now can use the new transformation.</section>
<section class="example"><h2 class="title sectiontitle">Examples</h2>
<figure class="fig fignone"><figcaption><span class="fig--title-label">Figure 1. </span>Creating a new print transformation</figcaption>
<p class="p">The following <span class="ph filepath">plugin.xml</span> file defines a new transformation type named "print-pdf"; it
also defines the transformation type to be a print type. The build will look for a
<span class="keyword parmname">dita2print-pdf</span> target.</p>
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;?xml-model href="https://www.dita-ot.org/rng/plugin.rnc" type="application/relax-ng-compact-syntax"?&gt;
&lt;plugin id="com.example.print-pdf"&gt;
&lt;require plugin="org.dita.pdf2"/&gt;
&lt;transtype name="print-pdf" extends="pdf" desc="PDF on A4 paper"/&gt;
&lt;feature extension="dita.transtype.print" value="print-pdf"/&gt;
&lt;feature extension="ant.import" file="integrator.xml"/&gt;
&lt;/plugin&gt;</code></pre>
<div class="note tip note_tip"><span class="note__title">Tip:</span> For a complete sample plug-in with all required code, see
<a class="xref" href="pdf-customization-example.html" title="This scenario walks through the process of creating a very simple plug-in (com.example.print-pdf) that creates a new transformation type: print-pdf.">Example: Creating a simple PDF plug-in</a>.</div>
</figure>
<figure class="fig fignone"><figcaption><span class="fig--title-label">Figure 2. </span>Defining new parameters</figcaption>
<p class="p">If your custom transformation type supports custom parameters, they can be defined in nested
<code class="keyword markupname xmlelement">&lt;param&gt;</code> elements within the <code class="keyword markupname xmlelement">&lt;transtype&gt;</code> element.</p>
<p class="p">While the <span class="ph filepath">org.dita.html5</span> plug-in was separated from <code class="ph codeph">common-html</code> in
version 2.4, the following example shows how earlier versions of that plug-in used the
<code class="keyword markupname xmlelement">&lt;transtype&gt;</code> element to extend the common HTML transformation with a new
<span class="keyword option">html5</span> transformation type and define a new <span class="keyword parmname">nav-toc</span> parameter with
three possible values:</p>
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code><strong class="ph b">&lt;transtype name="html5" extends="common-html" desc="HTML5"&gt;</strong>
&lt;param name="nav-toc" type="enum"
desc="Specifies whether to generate navigation in topic pages."&gt;
&lt;val default="true" desc="No TOC"&gt;none&lt;/val&gt;
&lt;val desc="Partial TOC that shows the current topic"&gt;partial&lt;/val&gt;
&lt;val desc="Full TOC"&gt;full&lt;/val&gt;
&lt;/param&gt;
&lt;/transtype&gt;</code></pre>
</figure>
</section>
</div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/plugin-use-cases.html" title="Plug-ins allow you to extend the functionality of DITA-OT. This might entail adding support for specialized document types, integrating processing overrides, or defining new output transformations.">Plug-in use cases</a></div></div><div class="linklist reltasks"><strong>Related tasks</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/plugins-installing.html" title="Use the dita install subcommand to install plug-ins.">Installing plug-ins</a></li></ul></div><div class="linklist relref"><strong>Related reference</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../extension-points/plugin-extension-points-general.html" title="These extension points enable you to extend DITA-OT. You can add Ant targets or imports; add a Java library to the classpath parameter; add a new transformation type; extend a catalog file; add new diagnostic messages, and more.">General extension points</a></li><li class="linklist"><a class="link" href="../topics/plugin-configfile.html" title="The plug-in descriptor file (plugin.xml) controls all aspects of a plug-in, making each extension visible to the rest of the toolkit. The file uses pre-defined extension points to locate changes, and then integrates those changes into the core DITA-OT code.">Plug-in descriptor file</a></li></ul></div></nav></article></main></body></html>

Some files were not shown because too many files have changed in this diff Show more