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

25
dita-ot-3.6/docsrc/topics/adding-plugins.dita Normal file
View file

@ -0,0 +1,25 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<concept id="ID">
<title>Adding and removing plug-ins</title>
<titlealts>
<navtitle>Adding plug-ins</navtitle>
</titlealts>
<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
<xref keyref="site-plugin-registry"/>.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>DITA
<indexterm>specializations</indexterm></indexterm>
<indexterm>plug-ins</indexterm>
<indexterm>plug-ins
<indexterm>working with</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<conbody/>
</concept>

30
dita-ot-3.6/docsrc/topics/ant.dita Normal file
View file

@ -0,0 +1,30 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<concept id="ant">
<title>Ant</title>
<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.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>Ant
<indexterm>overview</indexterm></indexterm>
<indexterm>build.xml</indexterm>
<indexterm>files
<indexterm>build.xml</indexterm></indexterm>
<indexterm>XSLT
<indexterm>Ant</indexterm></indexterm>
<indexterm>Java
<indexterm>Ant</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<conbody>
<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>The most important Ant script is the <filepath>build.xml</filepath> file. This script defines and combines common
pre-processing and output transformation routines; it also defines the DITA-OT extension points.</p>
</conbody>
</concept>

8
dita-ot-3.6/docsrc/topics/building-output.dita Normal file
View file

@ -0,0 +1,8 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<task id="tranforming-dita-content">
<title>Building output</title>
<shortdesc>You can use the <cmdname>dita</cmdname> command-line tool, Ant, or the Java API to transform DITA content
to the various output formats that DITA Open Toolkit supports.</shortdesc>
</task>

61
dita-ot-3.6/docsrc/topics/building-with-ant.dita Normal file
View file

@ -0,0 +1,61 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<task id="runant" xml:lang="en">
<title>Building output using Ant</title>
<shortdesc>You can build output by using an Ant build script to provide the DITA-OT parameters.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm><xmlatt>default</xmlatt></indexterm>
<indexterm>macOS
<indexterm>Ant</indexterm></indexterm>
<indexterm>Linux
<indexterm>Ant</indexterm></indexterm>
<indexterm>Windows
<indexterm>Ant</indexterm></indexterm>
<indexterm>Ant
<indexterm>publishing with</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<taskbody>
<steps>
<step>
<cmd conkeyref="conref-task/open-terminal"/>
</step>
<step>
<cmd>Issue the following command:</cmd>
<choicetable frame="topbot" relcolwidth="1* 3*" outputclass="multi-platform">
<chrow platform="linux mac">
<choption>Linux or macOS&#xA0;</choption>
<chdesc>
<cmdname>bin/ant</cmdname>
<option>-f</option>
<codeph><varname>build-script</varname>
<varname>target</varname></codeph>
</chdesc>
</chrow>
<chrow platform="windows">
<choption>Windows</choption>
<chdesc>
<cmdname>bin\ant</cmdname>
<option>-f</option>
<codeph><varname>build-script</varname>
<varname>target</varname></codeph>
</chdesc>
</chrow>
</choicetable>
<info> where:
<ul>
<li><varname>build-script</varname> is name of the Ant build script.</li>
<li><varname>target</varname> is an optional switch that specifies the name of the Ant target that you want
to run.
<p>If you do not specify a target, the value of the <xmlatt>default</xmlatt> attribute for the Ant project
is used.</p>
</li>
</ul></info>
</step>
</steps>
</taskbody>
</task>

106
dita-ot-3.6/docsrc/topics/creating-an-ant-build-script.dita Normal file
View file

@ -0,0 +1,106 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<task id="creating-an-ant-build-script">
<title>Creating an Ant build script</title>
<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.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm><xmlelement>link</xmlelement></indexterm>
<indexterm><xmlatt>name</xmlatt></indexterm>
<indexterm><xmlatt>default</xmlatt></indexterm>
<indexterm>Ant
<indexterm>build script</indexterm></indexterm>
<indexterm>relationship tables
<indexterm>PDF</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<taskbody>
<steps>
<step>
<cmd>Create an XML file that contains the following content:</cmd>
<info>
<codeblock
outputclass="language-xml normalize-space show-line-numbers show-whitespace"
>&lt;?xml version="1.0" encoding="UTF-8" ?>
&lt;project name="%project-name%" default="%default-target%" basedir=".">
&lt;property name="dita.dir" location="%path-to-DITA-OT%"/>
&lt;target name="%target-name%">
&lt;ant antfile="${dita.dir}/build.xml">
&lt;property name="args.input" value="%DITA-input%"/>
&lt;property name="transtype" value="html5"/>
&lt;/ant>
&lt;/target>
&lt;/project></codeblock>
</info>
<info>You will replace the placeholder content (indicated by the % signs) with content applicable to your
environment.</info>
</step>
<step>
<cmd>Specify project information:</cmd>
<substeps>
<substep importance="optional">
<cmd>Set the value of the <xmlatt>name</xmlatt> attribute to the name of your project.</cmd>
</substep>
<substep>
<cmd>Set the value of the <xmlatt>default</xmlatt> attribute to the name of a target in the build
script.</cmd>
<info>If the build script is invoked without specifying a target, this target will be run.</info>
</substep>
</substeps>
</step>
<step>
<cmd>Set the value of the <parmname>dita.dir</parmname> property to the location of the DITA-OT
installation.</cmd>
<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. </info>
</step>
<step>
<cmd>Create the Ant target:</cmd>
<substeps>
<substep>
<cmd>Set the value of the <xmlatt>name</xmlatt> attribute.</cmd>
</substep>
<substep>
<cmd>Specify the value for the <parmname>args.input</parmname> property.</cmd>
</substep>
<substep>
<cmd>Specify the value of the <parmname>transtype</parmname> property.</cmd>
</substep>
</substeps>
</step>
<step>
<cmd>Save the build script.</cmd>
</step>
</steps>
<example>
<p>The following Ant build script generates CHM and PDF output for the sample DITA maps.</p>
<p>
<codeblock outputclass="language-xml normalize-space show-line-numbers show-whitespace"><coderef
href="../samples/ant_sample/build-chm-pdf.xml"
/></codeblock></p>
<p>In addition to the mandatory parameters (<parmname>args.input</parmname> and <parmname>transtype</parmname>),
the chm and pdf targets each specify some optional parameters:
<ul>
<li>The <parmname>args.gen.task.lbl</parmname> property is set to YES, which ensures that headings are
automatically generated for the sections of task topics.</li>
<li>The <parmname>output.dir</parmname> property specifies where DITA-OT writes the output of the
transformations.</li>
</ul></p>
<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 <xmlelement>link</xmlelement> elements.</p>
<p>Finally, the all target simply specifies that both the chm and pdf target should be run.</p>
</example>
<postreq>Another resource for learning about Ant scripts are the files in the <filepath
conkeyref="conref-task/samples-dir"
/><filepath>/ant_sample/</filepath> 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.</postreq>
</taskbody>
</task>

117
dita-ot-3.6/docsrc/topics/creating-docker-images.dita Normal file
View file

@ -0,0 +1,117 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA General Task//EN" "generalTask.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<task id="ID">
<title>Installing plug-ins in a Docker image</title>
<titlealts>
<navtitle>Custom images</navtitle>
</titlealts>
<shortdesc>To install custom plug-ins or make other changes based on the DITA-OT parent image, you can create your own
<filepath>Dockerfile</filepath> and specify the official DITA-OT image as the basis for your image. </shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>plug-ins
<indexterm>installing in Docker images</indexterm></indexterm>
<indexterm>Docker images</indexterm>
</keywords>
</metadata>
</prolog>
<taskbody>
<context>
<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></context>
<steps>
<step>
<cmd>Create a new <filepath>Dockerfile</filepath> and specify the official DITA-OT image in the
<filepath>FROM</filepath> directive.</cmd>
<stepxmp>
<codeblock outputclass="language-dockerfile normalize-space show-line-numbers show-whitespace"><coderef
href="../samples/docker/Dockerfile#line-range(1,2)"
/></codeblock>
</stepxmp>
</step>
<step importance="optional">
<cmd>You can extend your image with a <codeph>RUN</codeph> declaration that runs the <cmdname>dita</cmdname>
command from the container to install a custom plug-in, and specify the filename or URL of the plug-in’s
distribution ZIP file.</cmd>
<stepxmp>
<codeblock outputclass="language-dockerfile normalize-space show-line-numbers show-whitespace"><coderef
href="../samples/docker/Dockerfile#line-range(4,5)"
/></codeblock>
</stepxmp>
</step>
<step importance="optional">
<cmd>You can also install custom plug-ins from the main DITA-OT plug-in registry at
<xref keyref="site-plugin-registry"/>, or from your company plug-in registry.</cmd>
<stepxmp>
<codeblock outputclass="language-dockerfile normalize-space show-line-numbers show-whitespace"><coderef
href="../samples/docker/Dockerfile#line-range(7,8)"
/></codeblock>
</stepxmp>
</step>
</steps>
<example>
<p>The <filepath>docsrc/samples</filepath> folder in the DITA-OT installation directory contains a complete
example:</p>
<fig>
<title>Sample Dockerfile with custom plug-ins: <filepath conkeyref="conref-task/samples-dir"/><filepath
>/docker/Dockerfile</filepath></title>
<codeblock outputclass="language-dockerfile normalize-space show-line-numbers show-whitespace"><coderef
href="../samples/docker/Dockerfile"
/></codeblock>
</fig>
</example>
<example>
<title>Building a new image</title>
<p>You can build a Docker image from this example by running the following command from the <filepath
conkeyref="conref-task/samples-dir"
/> directory:</p>
<codeblock outputclass="syntax-bash">$ <cmdname>docker</cmdname> 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:<keyword keyref="maintenance-version"/>
---> 9abb96827538
Step 2/3 : RUN dita --install https://github.com/infotexture/dita-bootstrap/archive/3.4.1.zip
---> Running in d510f874cae0
Added net.infotexture.dita-bootstrap
Removing intermediate container d510f874cae0
---> 63deb8e15b5b
Step 3/3 : RUN dita --install org.dita-community.pdf-page-break
---> Running in b4ef2fcad916
Added org.dita-community.pdf-page-break
Removing intermediate container b4ef2fcad916
---> 402885636b7f
Successfully built 402885636b7f
Successfully tagged sample-docker-image:1.0
</codeblock>
<p>Docker steps through each instruction in the Dockerfile to build the sample image. In this case, the
<cmdname>dita</cmdname> command provides feedback on each installed plug-in.</p>
</example>
<example>
<title>Running the new container</title>
<p>You can then start a container based on your new image:</p>
<codeblock outputclass="syntax-bash">$ <cmdname>docker</cmdname> 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</codeblock>
<p>This command sequence specifies the following options:
<ul>
<li><option>-v</option> mounts the <filepath>docsrc</filepath> subfolder of the DITA-OT directory on your host
machine and binds it to the <filepath>/src</filepath> volume in the container</li>
<li><option>-i</option> specifies <filepath conkeyref="conref-task/docsrc-dir"/><filepath
>/userguide.ditamap</filepath> as the input map file</li>
<li><option>-o</option> writes the output to <filepath conkeyref="conref-task/docsrc-dir"/><filepath
>/out/dita-bootstrap</filepath></li>
<li><option>-f</option> sets the output format to the Bootstrap template, and</li>
<li><option>-v</option> displays build progress messages with verbose logging</li>
</ul>
</p>
<p>When the build is finished, you should find a copy of the DITA-OT documentation under <filepath
conkeyref="conref-task/docsrc-dir"
/><filepath>/out/dita-bootstrap</filepath>, styled with the basic Bootstrap
template from the custom plug-in.</p>
</example>
</taskbody>
</task>

8
dita-ot-3.6/docsrc/topics/creating-plugins.ditamap Normal file
View file

@ -0,0 +1,8 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<map>
<title>Creating plug-ins</title>
<mapref href="plug-ins.ditamap"/>
<mapref href="migration.ditamap"/>
</map>

26
dita-ot-3.6/docsrc/topics/custom-plugins.dita Normal file
View file

@ -0,0 +1,26 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<concept id="custom-plugins">
<title>Creating custom plug-ins</title>
<titlealts>
<navtitle>Creating plug-ins</navtitle>
</titlealts>
<shortdesc id="plugins-creating">In addition to adding plug-ins from the plug-in registry at
<xref keyref="site-plugin-registry"/>, 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.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>DITA
<indexterm>specializations</indexterm></indexterm>
<indexterm>plug-ins</indexterm>
</keywords>
</metadata>
</prolog>
<conbody>
<p>A plug-in consists of a directory, typically stored within the <filepath>plugins/</filepath> subdirectory of the
DITA-OT installation. Every plug-in is controlled by a file named <filepath>plugin.xml</filepath>, which is
located in the root directory of the plug-in.</p>
</conbody>
</concept>

41
dita-ot-3.6/docsrc/topics/customizing.dita Normal file
View file

@ -0,0 +1,41 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<reference id="customizing">
<title>Customizing DITA Open Toolkit</title>
<titlealts>
<navtitle>Customizing DITA-OT</navtitle>
</titlealts>
<shortdesc>There are several ways to customize and extend the toolkit. You can adjust various aspects of the default
output by setting parameters or using custom stylesheets. For more complex customizations, use custom DITA-OT
plug-ins to override other parts of processing.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>plug-ins
<indexterm>best practices</indexterm></indexterm>
<indexterm>upgrading
<indexterm>default plug-ins</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<refbody>
<section>
<p>A single XSL file can be used as an override by passing it in as a parameter. For example, when building XHTML
content, the XSL parameter allows users to specify a single local XSL file (inside or outside of the toolkit)
that is called in place of the default XHTML code. Typically, this code imports the default processing code, and
overrides a couple of processing routines. This approach is best when the override is very minimal, or when the
style varies from build to build. However, any extension made with this sort of override is also possible with a
plug-in.</p>
<p>Creating a plug-in can be very simple to very complex, and is generally the best method for changing or
extending the toolkit. Plug-ins can be used to accomplish almost any modification that is needed for toolkit
processing, from minor style tweaks to extensive, complicated new output formats.</p>
<p>Editing DITA-OT code directly is strongly discouraged. Modifying the code directly significantly increases the
work and risk involved with future upgrades. It is also likely that such modifications will break plug-ins
provided by others, limiting the functions available to the toolkit.</p>
<note type="warning">Any changes made directly in the code 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.</note>
</section>
</refbody>
</reference>

43
dita-ot-3.6/docsrc/topics/determining-version-of-ditaot.dita Normal file
View file

@ -0,0 +1,43 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<task id="determining-version-of-dita-ot">
<title>Checking the DITA-OT version number</title>
<titlealts>
<navtitle>Checking the version</navtitle>
</titlealts>
<shortdesc>You can determine the DITA Open Toolkit version number from a command prompt.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>macOS
<indexterm>DITA-OT version</indexterm></indexterm>
<indexterm>Linux
<indexterm>DITA-OT version</indexterm></indexterm>
<indexterm>Windows
<indexterm>DITA-OT version</indexterm></indexterm>
<indexterm>command line
<indexterm>checking DITA-OT version</indexterm></indexterm>
<indexterm>installing
<indexterm>check current version</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<taskbody>
<steps>
<step>
<cmd conkeyref="conref-task/open-terminal"/>
</step>
<step>
<cmd>Issue the following command:</cmd>
<stepxmp>
<codeblock><filepath conkeyref="conref-task/dita-cmd"/> <parmname>--version</parmname></codeblock>
</stepxmp>
</step>
</steps>
<result>
<p>The DITA-OT version number appears on the console:</p>
<codeblock><systemoutput>DITA-OT version <keyword keyref="maintenance-version"/></systemoutput></codeblock>
</result>
</taskbody>
</task>

11
dita-ot-3.6/docsrc/topics/dita-and-dita-ot-resources.dita Normal file
View file

@ -0,0 +1,11 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<reference id="ID">
<title>DITA and DITA-OT resources</title>
<titlealts>
<navtitle>Resources</navtitle>
</titlealts>
<shortdesc>In addition to the DITA Open Toolkit documentation, there are other resources about DITA and DITA-OT that
you might find helpful.</shortdesc>
</reference>

50
dita-ot-3.6/docsrc/topics/dita-command-help.dita Normal file
View file

@ -0,0 +1,50 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<task id="accessing-help-from-the-cl-tool">
<title>Accessing help for the dita command</title>
<titlealts>
<navtitle>Command line help</navtitle>
</titlealts>
<shortdesc>You can access a list of subcommands and supported parameters for the <cmdname>dita</cmdname> command by
passing the <parmname>--help</parmname> option on the command line.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>macOS
<indexterm>help</indexterm></indexterm>
<indexterm>Linux
<indexterm>help</indexterm></indexterm>
<indexterm>Windows
<indexterm>help</indexterm></indexterm>
<indexterm>command line
<indexterm>help</indexterm></indexterm>
<indexterm><cmdname>dita</cmdname> command
<indexterm>help</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<taskbody>
<steps>
<step>
<cmd conkeyref="conref-task/open-terminal"/>
</step>
<step>
<cmd>Issue the following command:</cmd>
<stepxmp>
<codeblock><filepath conkeyref="conref-task/dita-cmd"/> <parmname>--help</parmname></codeblock>
</stepxmp>
</step>
<step importance="optional">
<cmd>For details on the arguments and options available for each subcommand, pass the
<parmname>--help</parmname> option after the subcommand name.</cmd>
<stepxmp>For example: <cmdname>dita install</cmdname>
<parmname>--help</parmname>.</stepxmp>
</step>
</steps>
<result>
<p>A brief usage summary appears in the command-line window, along with a list of subcommands, arguments, and
options.</p>
</result>
</taskbody>
</task>

129
dita-ot-3.6/docsrc/topics/dita-ot-day-2014.ditamap Normal file
View file

@ -0,0 +1,129 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<map>
<title>DITA-OT Day 2014</title>
<topicref keyref="dita-ot-day-videos-intro-2014" locktitle="yes">
<topicmeta>
<navtitle>2014 Munich</navtitle>
<linktext>Munich 2014</linktext>
</topicmeta>
<!-- This ditaval prevents duplicate titles in TOC and duplicated titles and shortdescs in the "mini-TOC" pages -->
<ditavalref href="../resources/ditaotdaykeys/all-conferences.ditaval"/>
<!-- See https://github.com/dita-ot/dita-ot/issues/3581 -->
<topicref keyref="quovadis-2014" toc="no"/>
<topicref keyref="providingdesignersaflexi-2014" toc="no"/>
<topicref keyref="publishingditacontentre--2014" toc="no"/>
<topicref keyref="scormwrapperforditatosco-2014" toc="no"/>
<topicref keyref="ditaopentoolkitpdfgenera-2014" toc="no"/>
<topicref keyref="ditaopentoolkitpdfplugin-2014" toc="no"/>
<topicref keyref="pdfsfromtheditaopentoolk-2014" toc="no"/>
<topicref keyref="dita2rdffromtreestotripl-2014" toc="no"/>
<topicref keyref="extendingtheditaopentool-2014" toc="no"/>
<topicref keyref="rngtodtdandxsdusingthedi-2014" toc="no"/>
<topicref keyref="contributingtothetoolkit-2014" toc="no"/>
<topicref keyref="lookingunderthehoodofthe-2014" toc="no"/>
<topicref keyref="overviewoftheditaopentoo-2014" toc="no"/>
</topicref>
<reltable>
<relheader>
<relcolspec linking="sourceonly"><!-- Source --></relcolspec>
<relcolspec linking="targetonly"><!-- Target --></relcolspec>
</relheader>
<relrow>
<relcell/>
<relcell>
<topicref keyref="quovadis-2014"/>
</relcell>
</relrow>
<relrow>
<relcell/>
<relcell>
<topicref keyref="providingdesignersaflexi-2014"/>
</relcell>
</relrow>
<relrow>
<relcell>
<topicref keyref="dita2eclipsehelp"/>
</relcell>
<relcell>
<topicref keyref="publishingditacontentre--2014"/>
</relcell>
</relrow>
<relrow>
<relcell>
<topicref keyref="dita-v1-2-support"/>
</relcell>
<relcell>
<topicref keyref="scormwrapperforditatosco-2014"/>
</relcell>
</relrow>
<relrow>
<relcell/>
<relcell>
<topicref keyref="ditaopentoolkitpdfgenera-2014"/>
</relcell>
</relrow>
<relrow>
<relcell>
<topicref keyref="pdf-customization-resources"/>
</relcell>
<relcell>
<topicref keyref="ditaopentoolkitpdfplugin-2014"/>
</relcell>
</relrow>
<relrow>
<relcell>
<topicref keyref="pdf-customization-resources"/>
</relcell>
<relcell>
<topicref keyref="pdfsfromtheditaopentoolk-2014"/>
</relcell>
</relrow>
<relrow>
<relcell/>
<relcell>
<topicref keyref="dita2rdffromtreestotripl-2014"/>
</relcell>
</relrow>
<relrow>
<relcell>
<topicref keyref="plugin-extension-points"/>
</relcell>
<relcell>
<topicref keyref="extendingtheditaopentool-2014"/>
</relcell>
</relrow>
<relrow>
<relcell>
<topicref keyref="dita-v1-3-support"/>
</relcell>
<relcell>
<topicref keyref="rngtodtdandxsdusingthedi-2014"/>
</relcell>
</relrow>
<relrow>
<relcell/>
<relcell>
<topicref keyref="contributingtothetoolkit-2014"/>
</relcell>
</relrow>
<relrow>
<relcell>
<topicref keyref="architecture"/>
</relcell>
<relcell>
<topicref keyref="lookingunderthehoodofthe-2014"/>
</relcell>
</relrow>
<relrow>
<relcell>
<topicref keyref="landing-page"/>
</relcell>
<relcell>
<topicref keyref="overviewoftheditaopentoo-2014"/>
</relcell>
</relrow>
</reltable>
</map>

151
dita-ot-3.6/docsrc/topics/dita-ot-day-2015.ditamap Normal file
View file

@ -0,0 +1,151 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<map>
<title>DITA-OT Day 2015</title>
<topicref keyref="dita-ot-day-videos-intro-2015" locktitle="yes">
<topicmeta>
<navtitle>2015 Munich</navtitle>
<linktext>Munich 2015</linktext>
</topicmeta>
<!-- This ditaval prevents duplicate titles in TOC and duplicated titles and shortdescs in the "mini-TOC" pages -->
<ditavalref href="../resources/ditaotdaykeys/all-conferences.ditaval"/>
<!-- See https://github.com/dita-ot/dita-ot/issues/3581 -->
<topicref keyref="dita-otdocumentationupda-2015" toc="no"/>
<topicref keyref="multipleotwithgit-2015" toc="no"/>
<topicref keyref="sellingditawithdemodata-2015" toc="no"/>
<topicref keyref="publishingwithdita-ot-th-2015" toc="no"/>
<topicref keyref="parametersannotationsfor-2015" toc="no"/>
<topicref keyref="howtorundita-ot-2015" toc="no"/>
<topicref keyref="creatingdita-otconstrain-2015" toc="no"/>
<topicref keyref="ditacommunity-2015" toc="no"/>
<topicref keyref="pdf5-mlplug-in-featuresf-2015" toc="no"/>
<topicref keyref="dita-otreloaded-2015" toc="no"/>
<topicref keyref="dita-otinsidetheblackbox-2015" toc="no"/>
<topicref keyref="pdfgenerationwithcss-2015" toc="no"/>
<topicref keyref="markdownplugin-2015" toc="no"/>
<topicref keyref="whystartcmdisnotyourfrie-2015" toc="no"/>
<topicref keyref="dita-otpatternsandanti-p-2015" toc="no"/>
<topicref keyref="whatsnewindita-ot-2015" toc="no"/>
</topicref>
<reltable>
<relheader>
<relcolspec linking="sourceonly"><!-- Source --></relcolspec>
<relcolspec linking="targetonly"><!-- Target --></relcolspec>
</relheader>
<relrow>
<relcell/>
<relcell>
<topicref keyref="whatsnewindita-ot-2015"/>
</relcell>
</relrow>
<relrow>
<relcell>
<topicref keyref="plugin-coding-conventions"/>
</relcell>
<relcell>
<topicref keyref="dita-otpatternsandanti-p-2015"/>
</relcell>
</relrow>
<relrow>
<relcell>
<topicref keyref="build-using-dita-command"/>
</relcell>
<relcell>
<topicref keyref="whystartcmdisnotyourfrie-2015"/>
</relcell>
</relrow>
<relrow>
<relcell>
<topicref keyref="dita2markdown"/>
<topicref keyref="markdown-input"/>
</relcell>
<relcell>
<topicref keyref="markdownplugin-2015"/>
</relcell>
</relrow>
<relrow>
<relcell/>
<relcell>
<topicref keyref="pdfgenerationwithcss-2015"/>
</relcell>
</relrow>
<relrow>
<relcell/>
<relcell>
<topicref keyref="dita-otinsidetheblackbox-2015"/>
</relcell>
</relrow>
<relrow>
<relcell/>
<relcell>
<topicref keyref="dita-otreloaded-2015"/>
</relcell>
</relrow>
<relrow>
<relcell/>
<relcell>
<topicref keyref="pdf5-mlplug-in-featuresf-2015"/>
</relcell>
</relrow>
<relrow>
<relcell>
<topicref keyref="plugin-implement-saxon-collation-uri-resolvers"/>
</relcell>
<relcell>
<topicref keyref="ditacommunity-2015"/>
</relcell>
</relrow>
<relrow>
<relcell>
<topicref keyref="plugin-use-cases"/>
</relcell>
<relcell>
<topicref keyref="creatingdita-otconstrain-2015"/>
</relcell>
</relrow>
<relrow>
<relcell>
<topicref keyref="building-output"/>
</relcell>
<relcell>
<topicref keyref="howtorundita-ot-2015"/>
</relcell>
</relrow>
<relrow>
<relcell>
<topicref keyref="parameters"/>
</relcell>
<relcell>
<topicref keyref="parametersannotationsfor-2015"/>
</relcell>
</relrow>
<relrow>
<relcell/>
<relcell>
<topicref keyref="publishingwithdita-ot-th-2015"/>
</relcell>
</relrow>
<relrow>
<relcell/>
<relcell>
<topicref keyref="sellingditawithdemodata-2015"/>
</relcell>
</relrow>
<relrow>
<relcell>
<topicref keyref="plugin-coding-conventions"/>
</relcell>
<relcell>
<topicref keyref="multipleotwithgit-2015"/>
</relcell>
</relrow>
<relrow>
<relcell/>
<relcell>
<topicref keyref="dita-otdocumentationupda-2015"/>
</relcell>
</relrow>
</reltable>
</map>

136
dita-ot-3.6/docsrc/topics/dita-ot-day-2016.ditamap Normal file
View file

@ -0,0 +1,136 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<map>
<title>DITA-OT Day 2016</title>
<topicref keyref="dita-ot-day-videos-intro-2016" locktitle="yes">
<topicmeta>
<navtitle>2016 Munich</navtitle>
<linktext>Munich 2016</linktext>
</topicmeta>
<!-- This ditaval prevents duplicate titles in TOC and duplicated titles and shortdescs in the "mini-TOC" pages -->
<ditavalref href="../resources/ditaotdaykeys/all-conferences.ditaval"/>
<!-- See https://github.com/dita-ot/dita-ot/issues/3581 -->
<topicref keyref="panel-2016" toc="no"/>
<topicref keyref="longtermdita-otplanning-2016" toc="no"/>
<topicref keyref="theuse-casesforaditatore-2016" toc="no"/>
<topicref keyref="ditaterminologymanagemen-2016" toc="no"/>
<topicref keyref="codeblockqualityassuranc-2016" toc="no"/>
<topicref keyref="testingindita-ot-2016" toc="no"/>
<topicref keyref="largescaleproductionusin-2016" toc="no"/>
<topicref keyref="usingtheopentoolkitthrou-2016" toc="no"/>
<topicref keyref="gotchaupgradingpdfplugin-2016" toc="no"/>
<topicref keyref="documentationdevelopment-2016" toc="no"/>
<topicref keyref="simplifiedcontributionpr-2016" toc="no"/>
<topicref keyref="dita-otinternalsandfutur-2016" toc="no"/>
<topicref keyref="sevenopen-sourcedita-otp-2016" toc="no"/>
<topicref keyref="internationalizationandt-2016" toc="no"/>
<topicref keyref="newdita-ot24releaseannou-2016" toc="no"/>
</topicref>
<reltable>
<relheader>
<relcolspec linking="sourceonly"><!-- Source --></relcolspec>
<relcolspec linking="targetonly"><!-- Target --></relcolspec>
</relheader>
<relrow>
<relcell/>
<relcell>
<topicref keyref="panel-2016" toc="no"/>
</relcell>
</relrow>
<relrow>
<relcell/>
<relcell>
<topicref keyref="longtermdita-otplanning-2016" toc="no"/>
</relcell>
</relrow>
<relrow>
<relcell>
<topicref keyref="dita2dita"/>
</relcell>
<relcell>
<topicref keyref="theuse-casesforaditatore-2016" toc="no"/>
</relcell>
</relrow>
<relrow>
<relcell>
<topicref keyref="plugins-registry"/>
</relcell>
<relcell>
<topicref keyref="ditaterminologymanagemen-2016" toc="no"/>
</relcell>
</relrow>
<relrow>
<relcell/>
<relcell>
<topicref keyref="codeblockqualityassuranc-2016" toc="no"/>
</relcell>
</relrow>
<relrow>
<relcell/>
<relcell>
<topicref keyref="testingindita-ot-2016" toc="no"/>
</relcell>
</relrow>
<relrow>
<relcell/>
<relcell>
<topicref keyref="largescaleproductionusin-2016" toc="no"/>
</relcell>
</relrow>
<relrow>
<relcell>
<topicref keyref="using-docker-images"/>
</relcell>
<relcell>
<topicref keyref="usingtheopentoolkitthrou-2016" toc="no"/>
</relcell>
</relrow>
<relrow>
<relcell>
<topicref keyref="migration"/>
</relcell>
<relcell>
<topicref keyref="gotchaupgradingpdfplugin-2016" toc="no"/>
</relcell>
</relrow>
<relrow>
<relcell/>
<relcell>
<topicref keyref="documentationdevelopment-2016" toc="no"/>
</relcell>
</relrow>
<relrow>
<relcell/>
<relcell>
<topicref keyref="simplifiedcontributionpr-2016" toc="no"/>
</relcell>
</relrow>
<relrow>
<relcell/>
<relcell>
<topicref keyref="dita-otinternalsandfutur-2016" toc="no"/>
</relcell>
</relrow>
<relrow>
<relcell/>
<relcell>
<topicref keyref="sevenopen-sourcedita-otp-2016" toc="no"/>
</relcell>
</relrow>
<relrow>
<relcell>
<topicref keyref="globalization"/>
</relcell>
<relcell>
<topicref keyref="internationalizationandt-2016" toc="no"/>
</relcell>
</relrow>
<relrow>
<relcell/>
<relcell>
<topicref keyref="newdita-ot24releaseannou-2016" toc="no"/>
</relcell>
</relrow>
</reltable>
</map>

138
dita-ot-3.6/docsrc/topics/dita-ot-day-2017.ditamap Normal file
View file

@ -0,0 +1,138 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<map>
<title>DITA-OT Day 2017</title>
<topicref keyref="dita-ot-day-videos-intro-2017" locktitle="yes">
<topicmeta>
<navtitle>2017 Berlin</navtitle>
<linktext>Berlin 2017</linktext>
</topicmeta>
<!-- This ditaval prevents duplicate titles in TOC and duplicated titles and shortdescs in the "mini-TOC" pages -->
<ditavalref href="../resources/ditaotdaykeys/all-conferences.ditaval"/>
<!-- See https://github.com/dita-ot/dita-ot/issues/3581 -->
<topicref keyref="panelwhatsnextfordita-ot-2017" toc="no"/>
<topicref keyref="whatarewemissingwherewou-2017" toc="no"/>
<topicref keyref="dcql-theditacascadingque-2017" toc="no"/>
<topicref keyref="locale-awaresortingandte-2017" toc="no"/>
<topicref keyref="automaticallycreatetarge-2017" toc="no"/>
<topicref keyref="bootstrappingdita-custom-2017" toc="no"/>
<topicref keyref="usingcsstostylethepdfout-2017" toc="no"/>
<topicref keyref="markdownsupportinside-ou-2017" toc="no"/>
<topicref keyref="dita-otdocsdevelopments-2017" toc="no"/>
<topicref keyref="managingalargescalebuild-2017" toc="no"/>
<topicref keyref="generatingsvgsyntaxdiagr-2017" toc="no"/>
<topicref keyref="ditavalidationandspell-c-2017" toc="no"/>
<topicref keyref="accessibilityindita-ot-2017" toc="no"/>
<topicref keyref="weshallcallitpreprocess2-2017" toc="no"/>
<topicref keyref="dita-ot-2017" toc="no"/>
</topicref>
<reltable>
<relheader>
<relcolspec linking="sourceonly"><!-- Source --></relcolspec>
<relcolspec linking="targetonly"><!-- Target --></relcolspec>
</relheader>
<relrow>
<relcell/>
<relcell>
<topicref keyref="panelwhatsnextfordita-ot-2017"/>
</relcell>
</relrow>
<relrow>
<relcell/>
<relcell>
<topicref keyref="whatarewemissingwherewou-2017"/>
</relcell>
</relrow>
<relrow>
<relcell/>
<relcell>
<topicref keyref="dcql-theditacascadingque-2017"/>
</relcell>
</relrow>
<relrow>
<relcell>
<topicref keyref="globalization"/>
</relcell>
<relcell>
<topicref keyref="locale-awaresortingandte-2017"/>
</relcell>
</relrow>
<relrow>
<relcell/>
<relcell>
<topicref keyref="automaticallycreatetarge-2017"/>
</relcell>
</relrow>
<relrow>
<relcell>
<topicref keyref="html-customization"/>
</relcell>
<relcell>
<topicref keyref="bootstrappingdita-custom-2017"/>
</relcell>
</relrow>
<relrow>
<relcell/>
<relcell>
<topicref keyref="usingcsstostylethepdfout-2017"/>
</relcell>
</relrow>
<relrow>
<relcell>
<topicref keyref="dita2markdown"/>
</relcell>
<relcell>
<topicref keyref="markdownsupportinside-ou-2017"/>
</relcell>
</relrow>
<relrow>
<relcell/>
<relcell>
<topicref keyref="dita-otdocsdevelopments-2017"/>
</relcell>
</relrow>
<relrow>
<relcell>
<topicref keyref="plugin-coding-conventions"/>
</relcell>
<relcell>
<topicref keyref="managingalargescalebuild-2017"/>
</relcell>
</relrow>
<relrow>
<relcell/>
<relcell>
<topicref keyref="generatingsvgsyntaxdiagr-2017"/>
</relcell>
</relrow>
<relrow>
<relcell/>
<relcell>
<topicref keyref="ditavalidationandspell-c-2017"/>
</relcell>
</relrow>
<relrow>
<relcell>
<topicref keyref="dita-v1-3-support"/>
</relcell>
<relcell>
<topicref keyref="accessibilityindita-ot-2017"/>
</relcell>
</relrow>
<relrow>
<relcell>
<topicref keyref="map-first-preproc"/>
</relcell>
<relcell>
<topicref keyref="weshallcallitpreprocess2-2017"/>
</relcell>
</relrow>
<relrow>
<relcell/>
<relcell>
<topicref keyref="dita-ot-2017"/>
</relcell>
</relrow>
</reltable>
</map>

152
dita-ot-3.6/docsrc/topics/dita-ot-day-2018.ditamap Normal file
View file

@ -0,0 +1,152 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<map>
<title>DITA-OT Day 2018</title>
<topicref keyref="dita-ot-day-videos-intro-2018" locktitle="yes">
<topicmeta>
<navtitle>2018 Rotterdam</navtitle>
<linktext>Rotterdam 2018</linktext>
</topicmeta>
<!-- This ditaval prevents duplicate titles in TOC and duplicated titles and shortdescs in the "mini-TOC" pages -->
<ditavalref href="../resources/ditaotdaykeys/all-conferences.ditaval"/>
<!-- See https://github.com/dita-ot/dita-ot/issues/3581 -->
<topicref keyref="whatsnextfordita-ot-2018" toc="no"/>
<topicref keyref="whoareyoucallingstale-2018" toc="no"/>
<topicref keyref="twistedxslttricksmakingc-2018" toc="no"/>
<topicref keyref="dita-otanddocops-2018" toc="no"/>
<topicref keyref="validationmeetspublicati-2018" toc="no"/>
<topicref keyref="afastpathforbuildingdata-2018" toc="no"/>
<topicref keyref="overviewofdita-semiaopen-2018" toc="no"/>
<topicref keyref="unittestingdita-otplugin-2018" toc="no"/>
<topicref keyref="stepbystepimplementation-2018" toc="no"/>
<topicref keyref="metaditasamplestestingar-2018" toc="no"/>
<topicref keyref="plug-ininstallationmadee-2018" toc="no"/>
<topicref keyref="installingdita-otonmacos-2018" toc="no"/>
<topicref keyref="comparisonbetweenthedocb-2018" toc="no"/>
<topicref keyref="ditagradleandgitasmallte-2018" toc="no"/>
<topicref keyref="dita-otwebsitesurveyresu-2018" toc="no"/>
<topicref keyref="highlightsinrecentdita-o-2018" toc="no"/>
</topicref>
<reltable>
<relheader>
<relcolspec linking="sourceonly"><!-- Source --></relcolspec>
<relcolspec linking="targetonly"><!-- Target --></relcolspec>
</relheader>
<relrow>
<relcell/>
<relcell>
<topicref keyref="whatsnextfordita-ot-2018"/>
</relcell>
</relrow>
<relrow>
<relcell/>
<relcell>
<topicref keyref="whoareyoucallingstale-2018"/>
</relcell>
</relrow>
<relrow>
<relcell>
<topicref keyref="pdf-customization-resources"/>
</relcell>
<relcell>
<topicref keyref="twistedxslttricksmakingc-2018"/>
</relcell>
</relrow>
<relrow>
<relcell/>
<relcell>
<topicref keyref="dita-otanddocops-2018"/>
</relcell>
</relrow>
<relrow>
<relcell>
<topicref keyref="plugins-registry"/>
<topicref keyref="plugin-coding-conventions"/>
</relcell>
<relcell>
<topicref keyref="validationmeetspublicati-2018"/>
</relcell>
</relrow>
<relrow>
<relcell/>
<relcell>
<topicref keyref="afastpathforbuildingdata-2018"/>
</relcell>
</relrow>
<relrow>
<relcell>
<topicref keyref="plugins-registry"/>
</relcell>
<relcell>
<topicref keyref="overviewofdita-semiaopen-2018"/>
</relcell>
</relrow>
<relrow>
<relcell>
<topicref keyref="plugins-registry"/>
<topicref keyref="plugin-coding-conventions"/>
</relcell>
<relcell>
<topicref keyref="unittestingdita-otplugin-2018"/>
</relcell>
</relrow>
<relrow>
<relcell>
<topicref keyref="custom-plugins"/>
</relcell>
<relcell>
<topicref keyref="stepbystepimplementation-2018"/>
</relcell>
</relrow>
<relrow>
<relcell>
<topicref keyref="plugin-coding-conventions"/>
</relcell>
<relcell>
<topicref keyref="metaditasamplestestingar-2018"/>
</relcell>
</relrow>
<relrow>
<relcell>
<topicref keyref="plugins-installing"/>
<topicref keyref="plugins-registry"/>
</relcell>
<relcell>
<topicref keyref="plug-ininstallationmadee-2018"/>
</relcell>
</relrow>
<relrow>
<relcell>
<topicref keyref="installing-via-homebrew"/>
</relcell>
<relcell>
<topicref keyref="installingdita-otonmacos-2018"/>
</relcell>
</relrow>
<relrow>
<relcell/>
<relcell>
<topicref keyref="comparisonbetweenthedocb-2018"/>
</relcell>
</relrow>
<relrow>
<relcell/>
<relcell>
<topicref keyref="ditagradleandgitasmallte-2018"/>
</relcell>
</relrow>
<relrow>
<relcell/>
<relcell>
<topicref keyref="dita-otwebsitesurveyresu-2018"/>
</relcell>
</relrow>
<relrow>
<relcell/>
<relcell>
<topicref keyref="highlightsinrecentdita-o-2018"/>
</relcell>
</relrow>
</reltable>
</map>

140
dita-ot-3.6/docsrc/topics/dita-ot-day-2019.ditamap Normal file
View file

@ -0,0 +1,140 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<map>
<title>DITA-OT Day 2019</title>
<topicref keyref="dita-ot-day-videos-intro-2019" locktitle="yes">
<topicmeta>
<navtitle>2019 Brussels</navtitle>
<linktext>Brussels 2019</linktext>
</topicmeta>
<!-- This ditaval prevents duplicate titles in TOC and duplicated titles and shortdescs in the "mini-TOC" pages -->
<ditavalref href="../resources/ditaotdaykeys/all-conferences.ditaval"/>
<!-- See https://github.com/dita-ot/dita-ot/issues/3581 -->
<topicref keyref="dita-otshoptalk-2019" toc="no"/>
<topicref keyref="easyaspiepdfcustomizatio-2019" toc="no"/>
<topicref keyref="generatingmetricsfromyou-2019" toc="no"/>
<topicref keyref="casestudyoftaxonomyandse-2019" toc="no"/>
<topicref keyref="documentationdevelopment-2019" toc="no"/>
<topicref keyref="theartofdoingnothing-2019" toc="no"/>
<topicref keyref="allthecoolkidsareusingth-2019" toc="no"/>
<topicref keyref="allthecoolkidsareusingja-2019" toc="no"/>
<topicref keyref="editingditaopentoolkitpr-2019" toc="no"/>
<topicref keyref="onefiletorulethemalldita-2019" toc="no"/>
<topicref keyref="ah-wmldita-to-wordplug-i-2019" toc="no"/>
<topicref keyref="varioususefulopensourcep-2019" toc="no"/>
<topicref keyref="runningonsomeoneelsescom-2019" toc="no"/>
<topicref keyref="trimyourtoolkitwiththiso-2019" toc="no"/>
<topicref keyref="newsandannouncements-2019" toc="no"/>
</topicref>
<reltable>
<relheader>
<relcolspec linking="sourceonly"><!-- Source --></relcolspec>
<relcolspec linking="targetonly"><!-- Target --></relcolspec>
</relheader>
<relrow>
<relcell/>
<relcell>
<topicref keyref="dita-otshoptalk-2019" toc="no"/>
</relcell>
</relrow>
<relrow>
<relcell/>
<relcell>
<topicref keyref="easyaspiepdfcustomizatio-2019" toc="no"/>
</relcell>
</relrow>
<relrow>
<relcell/>
<relcell>
<topicref keyref="generatingmetricsfromyou-2019" toc="no"/>
</relcell>
</relrow>
<relrow>
<relcell/>
<relcell>
<topicref keyref="casestudyoftaxonomyandse-2019" toc="no"/>
</relcell>
</relrow>
<relrow>
<relcell/>
<relcell>
<topicref keyref="documentationdevelopment-2019" toc="no"/>
</relcell>
</relrow>
<relrow>
<relcell>
<topicref keyref="plugins-registry"/>
</relcell>
<relcell>
<topicref keyref="theartofdoingnothing-2019" toc="no"/>
</relcell>
</relrow>
<relrow>
<relcell>
<topicref keyref="plugins-registry"/>
</relcell>
<relcell>
<topicref keyref="allthecoolkidsareusingth-2019" toc="no"/>
</relcell>
</relrow>
<relrow>
<relcell>
<topicref keyref="plugins-registry"/>
</relcell>
<relcell>
<topicref keyref="allthecoolkidsareusingja-2019" toc="no"/>
</relcell>
</relrow>
<relrow>
<relcell>
<topicref keyref="using-project-files"/>
</relcell>
<relcell>
<topicref keyref="editingditaopentoolkitpr-2019" toc="no"/>
</relcell>
</relrow>
<relrow>
<relcell>
<topicref keyref="using-project-files"/>
</relcell>
<relcell>
<topicref keyref="onefiletorulethemalldita-2019" toc="no"/>
</relcell>
</relrow>
<relrow>
<relcell>
<topicref keyref="plugins-registry"/>
</relcell>
<relcell>
<topicref keyref="ah-wmldita-to-wordplug-i-2019" toc="no"/>
</relcell>
</relrow>
<relrow>
<relcell/>
<relcell>
<topicref keyref="varioususefulopensourcep-2019" toc="no"/>
</relcell>
</relrow>
<relrow>
<relcell/>
<relcell>
<topicref keyref="runningonsomeoneelsescom-2019" toc="no"/>
</relcell>
</relrow>
<relrow>
<relcell>
<topicref keyref="plugins-removing"/>
</relcell>
<relcell>
<topicref keyref="trimyourtoolkitwiththiso-2019" toc="no"/>
</relcell>
</relrow>
<relrow>
<relcell/>
<relcell>
<topicref keyref="newsandannouncements-2019" toc="no"/>
</relcell>
</relrow>
</reltable>
</map>

17
dita-ot-3.6/docsrc/topics/dita-ot-day-videos-intro-2014.dita Normal file
View file

@ -0,0 +1,17 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<concept id="dita_ot_day_videos_intro">
<title>DITA-OT Day Conference – Munich 2014</title>
<shortdesc>November 20, 2014 in Munich, Germany.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>DITA-OT Day 2014 videos</indexterm>
</keywords>
</metadata>
</prolog>
<conbody>
<p/>
</conbody>
</concept>

17
dita-ot-3.6/docsrc/topics/dita-ot-day-videos-intro-2015.dita Normal file
View file

@ -0,0 +1,17 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<concept id="dita_ot_day_videos_intro">
<title>DITA-OT Day Conference – Munich 2015</title>
<shortdesc>November 15, 2015 in Munich, Germany.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>DITA-OT Day 2015 videos</indexterm>
</keywords>
</metadata>
</prolog>
<conbody>
<p/>
</conbody>
</concept>

17
dita-ot-3.6/docsrc/topics/dita-ot-day-videos-intro-2016.dita Normal file
View file

@ -0,0 +1,17 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<concept id="dita_ot_day_videos_intro">
<title>DITA-OT Day Conference – Munich 2016</title>
<shortdesc>November 13, 2016 in Munich, Germany.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>DITA-OT Day 2016 videos</indexterm>
</keywords>
</metadata>
</prolog>
<conbody>
<p/>
</conbody>
</concept>

17
dita-ot-3.6/docsrc/topics/dita-ot-day-videos-intro-2017.dita Normal file
View file

@ -0,0 +1,17 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<concept id="dita_ot_day_videos_intro">
<title>DITA-OT Day Conference – Berlin 2017</title>
<shortdesc>October 29, 2017 in Berlin, Germany.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>DITA-OT Day 2017 videos</indexterm>
</keywords>
</metadata>
</prolog>
<conbody>
<p/>
</conbody>
</concept>

17
dita-ot-3.6/docsrc/topics/dita-ot-day-videos-intro-2018.dita Normal file
View file

@ -0,0 +1,17 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<concept id="dita_ot_day_videos_intro">
<title>DITA-OT Day Conference – Rotterdam 2018</title>
<shortdesc>November 4, 2018 in Rotterdam, Netherlands.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>DITA-OT Day 2018 videos</indexterm>
</keywords>
</metadata>
</prolog>
<conbody>
<p/>
</conbody>
</concept>

18
dita-ot-3.6/docsrc/topics/dita-ot-day-videos-intro-2019.dita Normal file
View file

@ -0,0 +1,18 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<concept id="dita_ot_day_videos_intro">
<title>DITA-OT Day Conference – Brussels 2019</title>
<shortdesc>November 9, 2019 in Brussels, Belgium.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>DITA-OT Day 2019 videos</indexterm>
<indexterm>videos</indexterm>
</keywords>
</metadata>
</prolog>
<conbody>
<p/>
</conbody>
</concept>

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

@ -0,0 +1,13 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<concept id="dita_ot_day_videos">
<title>DITA-OT Day Conference Recordings</title>
<titlealts>
<navtitle>DITA-OT Day Videos</navtitle>
</titlealts>
<shortdesc>All video recordings from each DITA-OT Day conference from 2014 onward.</shortdesc>
<conbody>
<p/>
</conbody>
</concept>

15
dita-ot-3.6/docsrc/topics/dita-ot-day-videos.ditamap Normal file
View file

@ -0,0 +1,15 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<map>
<title>DITA-OT Day Videos</title>
<topicref keyref="dita-ot-day-videos">
<ditavalref href="../resources/ditaotdaykeys/all-conferences.ditaval"/>
<mapref href="dita-ot-day-2019.ditamap"/>
<mapref href="dita-ot-day-2018.ditamap"/>
<mapref href="dita-ot-day-2017.ditamap"/>
<mapref href="dita-ot-day-2016.ditamap"/>
<mapref href="dita-ot-day-2015.ditamap"/>
<mapref href="dita-ot-day-2014.ditamap"/>
</topicref>
</map>

51
dita-ot-3.6/docsrc/topics/dita-resources.ditamap Normal file
View file

@ -0,0 +1,51 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<map>
<title>DITA and DITA-OT resources</title>
<topicref format="html" href="https://www.dita-ot.org" scope="external">
<topicmeta>
<linktext>DITA-OT project website: dita-ot.org</linktext>
<shortdesc>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.</shortdesc>
</topicmeta>
</topicref>
<topicref format="html" href="https://groups.io/g/dita-users" scope="external">
<topicmeta>
<linktext>DITA Users group</linktext>
<shortdesc>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.</shortdesc>
</topicmeta>
</topicref>
<topicref format="html" href="https://groups.google.com/d/forum/dita-ot-users" scope="external">
<topicmeta>
<linktext>DITA-OT Users Google Group</linktext>
<shortdesc>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.</shortdesc>
</topicmeta>
</topicref>
<topicref format="html" href="https://dita-ot.slack.com" scope="external">
<topicmeta>
<linktext>DITA-OT Slack workspace</linktext>
<shortdesc>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
<xref href="http://slack.dita-ot.org" format="html" scope="external">slack.dita-ot.org</xref>.</shortdesc>
</topicmeta>
</topicref>
<topicref format="html" href="http://www.oasis-open.org/committees/dita/" scope="external">
<topicmeta>
<linktext>Home page for the DITA Technical Committee</linktext>
<shortdesc>The OASIS DITA Technical Committee develops the DITA standard.</shortdesc>
</topicmeta>
</topicref>
<topicref format="html" href="http://dita-archive.xml.org/wiki/the-dita-open-toolkit" scope="external">
<topicmeta>
<linktext>DITA-OT project archive</linktext>
<shortdesc>The DITA-OT project archive at dita-archive.xml.org provides news about earlier toolkit releases, and
release notes for legacy versions.</shortdesc>
</topicmeta>
</topicref>
<topicref keyref="books"/>
</map>

16
dita-ot-3.6/docsrc/topics/dita-xml-input.dita Normal file
View file

@ -0,0 +1,16 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<topic id="ID">
<title>Standard DITA XML</title>
<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 <keyword keyref="release"/>, DITA-OT also provides an initial preview of features for the
latest draft of the upcoming DITA 2.0 standard.</shortdesc>
<body>
<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
<xref keyref="dita13-spec"/> is the authoritative source of information on authoring DITA content in XML.</p>
<note type="tip">For details on how DITA Open Toolkit processes DITA XML content, see
<xref keyref="dita-spec-support"/>.</note>
</body>
</topic>

67
dita-ot-3.6/docsrc/topics/dita2dita.dita Normal file
View file

@ -0,0 +1,67 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<topic id="normalized-dita">
<title>Normalized DITA</title>
<shortdesc>The <codeph>dita</codeph> 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.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm><cmdname>dita</cmdname> command
<indexterm>normalized DITA</indexterm></indexterm>
<indexterm>transformations
<indexterm>normalized DITA</indexterm></indexterm>
<indexterm>DITA
<indexterm>normalized</indexterm></indexterm>
<indexterm>metadata
<indexterm>map</indexterm></indexterm>
<indexterm>metadata
<indexterm>topic</indexterm></indexterm>
<indexterm>plug-ins
<indexterm>dita2dita</indexterm></indexterm>
<indexterm>dita2dita</indexterm>
<indexterm>relationship tables
<indexterm>normalized DITA</indexterm></indexterm>
<indexterm>converting lightweight formats to DITA</indexterm>
</keywords>
</metadata>
</prolog>
<body>
<p>In comparison to the source DITA files, the normalized DITA files are modified in the following ways:</p>
<ul>
<li>References from one DITA map to another are resolved</li>
<li>Map-based links, such as those generated by map hierarchy and relationship tables, are added to the
topics.</li>
<li>Link text is resolved.</li>
<li>Map attributes that cascade are made explicit on child elements.</li>
<li>Map metadata such as index entries and copyrights are pushed into topics.</li>
<li>Topic metadata such as navigation titles, link text and short descriptions are pulled from topics into the
map.</li>
<li>XML comments are removed.</li>
</ul>
<section id="applications">
<title>Applications</title>
<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>
<note type="tip">You can also use the normalized DITA transformation to convert
<xref keyref="markdown-input">Markdown</xref> or
<xref keyref="lwdita-input">Lightweight DITA</xref> 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.</note>
</section>
<section id="generating-normalized-dita-output">
<title>Generating normalized DITA output</title>
<p>Run the <cmdname>dita</cmdname> command and set the value of the output <parmname>--format</parmname> option to
<option>dita</option>:</p>
<codeblock><filepath conkeyref="conref-task/dita-cmd"/> <parmname>--input</parmname>=<varname
>input-file</varname> <parmname>--format</parmname>=<option>dita</option></codeblock>
<p>where:</p>
<ul>
<li conkeyref="conref-task/novice-variables"/>
</ul>
</section>
</body>
</topic>

64
dita-ot-3.6/docsrc/topics/dita2eclipsehelp.dita Normal file
View file

@ -0,0 +1,64 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<concept id="dita2eclipsehelp">
<title>Eclipse help</title>
<shortdesc>The <option>eclipsehelp</option> transformation generates XHTML output, CSS files, and the control files
that are needed for Eclipse help.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>transformations
<indexterm>Eclipse Help</indexterm></indexterm>
<indexterm>Eclipse Help
<index-see-also>transformations</index-see-also></indexterm>
<indexterm>plug-ins
<indexterm>dita2eclipsehelp</indexterm></indexterm>
<indexterm>dita2eclipsehelp</indexterm>
<indexterm>CSS
<indexterm>Eclipse Help</indexterm></indexterm>
<indexterm>table of contents
<indexterm>Eclipse Help</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<conbody>
<p>In addition to the XHTML output and CSS files, this transformation returns the following files, where
<varname>mapname</varname> is the name of the master DITA map.</p>
<simpletable outputclass="table-hover" frame="all" relcolwidth="2* 3*">
<sthead>
<stentry>File name</stentry>
<stentry>Description</stentry>
</sthead>
<strow>
<stentry><filepath>plugin.xml</filepath></stentry>
<stentry>Control file for the Eclipse plug-in</stentry>
</strow>
<strow>
<stentry><filepath><varname>mapname</varname>.xml</filepath></stentry>
<stentry>Table of contents</stentry>
</strow>
<strow>
<stentry><filepath>index.xml</filepath></stentry>
<stentry>Index file</stentry>
</strow>
<strow>
<stentry><filepath>plugin.properties</filepath></stentry>
<stentry/>
</strow>
<strow>
<stentry><filepath>META-INF/MANIFEST.MF</filepath></stentry>
<stentry/>
</strow>
</simpletable>
<p>To run the Eclipse help transformation, set the <parmname>transtype</parmname> parameter to
<option>eclipsehelp</option>, or pass the <parmname>--format</parmname>=<option>eclipsehelp</option> option to
the <cmdname>dita</cmdname> command line.</p>
<codeblock><filepath conkeyref="conref-task/dita-cmd"/> <parmname>--input</parmname>=<varname
>input-file</varname> <parmname>--format</parmname>=<option>eclipsehelp</option></codeblock>
<p>where:</p>
<ul>
<li conkeyref="conref-task/novice-variables"/>
</ul>
</conbody>
</concept>

47
dita-ot-3.6/docsrc/topics/dita2html5.dita Normal file
View file

@ -0,0 +1,47 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<concept id="dita2html5" xml:lang="en">
<title>HTML5</title>
<shortdesc>The <option>html5</option> transformation generates HTML5 output and a table of contents (TOC)
file.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm><xmlelement>nav</xmlelement></indexterm>
<indexterm>languages
<indexterm>right-to-left</indexterm></indexterm>
<indexterm>HTML
<index-see-also>HTML5</index-see-also></indexterm>
<indexterm>HTML5
<index-see-also>transformations</index-see-also></indexterm>
<indexterm>transformations
<indexterm>HTML5</indexterm></indexterm>
<indexterm>plug-ins
<indexterm>dita2html5</indexterm></indexterm>
<indexterm>dita2html5</indexterm>
<indexterm>CSS
<indexterm>HTML5</indexterm></indexterm>
<indexterm>HTML5
<indexterm>CSS</indexterm></indexterm>
<indexterm>table of contents
<indexterm>HTML5</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<conbody>
<p>The HTML5 output is always associated with the default DITA-OT CSS file (<filepath>commonltr.css</filepath> or
<filepath>commonrtl.css</filepath> for right-to-left languages). You can use toolkit parameters to add a custom
style sheet that overrides the default styles, or generate a <xmlelement>nav</xmlelement> element with a
navigation TOC in topic pages.</p>
<p>To run the HTML5 transformation, set the <parmname>transtype</parmname> parameter to <option>html5</option>, or
pass the <parmname>--format</parmname>=<option>html5</option> option to the <cmdname>dita</cmdname> command
line.</p>
<codeblock><filepath conkeyref="conref-task/dita-cmd"/> <parmname>--input</parmname>=<varname
>input-file</varname> <parmname>--format</parmname>=<option>html5</option></codeblock>
<p>where:</p>
<ul>
<li conkeyref="conref-task/novice-variables"/>
</ul>
</conbody>
</concept>

71
dita-ot-3.6/docsrc/topics/dita2htmlhelp.dita Normal file
View file

@ -0,0 +1,71 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<concept id="dita2htmlhelp">
<title>HTML Help</title>
<shortdesc>The <option>htmlhelp</option> transformation generates HTML output, CSS files, and the control files that
are needed to produce a Microsoft Compiled HTML Help (.chm) file.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>transformations
<indexterm>HTML Help</indexterm></indexterm>
<indexterm>HTML Help
<index-see-also>transformations</index-see-also></indexterm>
<indexterm>CHM
<index-see>HTML Help</index-see></indexterm>
<indexterm>Microsoft HTML Help Workshop</indexterm>
<indexterm>.hhc</indexterm>
<indexterm>.hhk</indexterm>
<indexterm>.hhp</indexterm>
<indexterm>plug-ins
<indexterm>dita2htmlhelp</indexterm></indexterm>
<indexterm>dita2htmlhelp</indexterm>
<indexterm>CSS
<indexterm>HTML Help</indexterm></indexterm>
<indexterm>index
<indexterm>HTML Help</indexterm></indexterm>
<indexterm>table of contents
<indexterm>HTML Help</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<conbody>
<p>In addition to the HTML output and CSS files, this transformation returns the following files, where
<varname>mapname</varname> is the name of the master DITA map.</p>
<simpletable outputclass="table-hover" frame="all" relcolwidth="2* 3*">
<sthead>
<stentry>File name</stentry>
<stentry>Description</stentry>
</sthead>
<strow>
<stentry><filepath><varname>mapname</varname>.hhc</filepath></stentry>
<stentry>Table of contents</stentry>
</strow>
<strow>
<stentry><filepath><varname>mapname</varname>.hhk</filepath></stentry>
<stentry>Sorted index</stentry>
</strow>
<strow>
<stentry><filepath><varname>mapname</varname>.hhp</filepath></stentry>
<stentry>HTML Help project file</stentry>
</strow>
<strow>
<stentry><filepath><varname>mapname</varname>.chm</filepath></stentry>
<stentry>
<p>Compiled HTML Help file</p>
<note>The compiled file is only generated if the HTML Help Workshop is installed on the build system.</note>
</stentry>
</strow>
</simpletable>
<p>To run the HTML Help transformation, set the <parmname>transtype</parmname> parameter to
<option>htmlhelp</option>, or pass the <parmname>--format</parmname>=<option>htmlhelp</option> option to the
<cmdname>dita</cmdname> command line.</p>
<codeblock><filepath conkeyref="conref-task/dita-cmd"/> <parmname>--input</parmname>=<varname
>input-file</varname> <parmname>--format</parmname>=<option>htmlhelp</option></codeblock>
<p>where:</p>
<ul>
<li conkeyref="conref-task/novice-variables"/>
</ul>
</conbody>
</concept>

53
dita-ot-3.6/docsrc/topics/dita2markdown.dita Normal file
View file

@ -0,0 +1,53 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<topic id="markdown">
<title>Markdown</title>
<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.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>Markdown</indexterm>
<indexterm>transformations
<indexterm>Markdown</indexterm></indexterm>
<indexterm>GitHub-Flavored Markdown</indexterm>
<indexterm>GitBook</indexterm>
<indexterm>plug-ins
<indexterm>dita2markdown</indexterm></indexterm>
<indexterm>dita2markdown</indexterm>
<indexterm>table of contents
<indexterm>Markdown</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<body>
<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 id="generating-markdown-output">
<title>Generating Markdown output</title>
<p>Markdown output can be generated by passing one of the following transformation types to the dita command with
the <parmname>--format</parmname> option:</p>
<ul>
<li>
<p>To publish Markdown DITA files, use the <option>markdown</option> transtype.</p></li>
<li>
<p>To generate
<xref keyref="gfm-spec"/> files, use the <option>markdown_github</option> transtype.</p></li>
<li>
<p>To publish GitHub-Flavored Markdown and generate a <filepath>SUMMARY.md</filepath> table of contents file
for publication via
<xref format="html" href="https://www.gitbook.com" scope="external">GitBook</xref>, use the
<option>markdown_gitbook</option> transtype.</p></li>
</ul>
<p>Run the <cmdname>dita</cmdname> command and set the value of the output <parmname>--format</parmname> option to
the desired format, for example:</p>
<codeblock><filepath conkeyref="conref-task/dita-cmd"/> <parmname>--input</parmname>=<varname
>input-file</varname> <parmname>--format</parmname>=<option>markdown</option></codeblock>
<p>where:</p>
<ul>
<li conkeyref="conref-task/novice-variables"/>
</ul></section>
</body>
</topic>

35
dita-ot-3.6/docsrc/topics/dita2pdf.dita Normal file
View file

@ -0,0 +1,35 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<concept id="dita2pdf">
<title>PDF</title>
<shortdesc>The <option>pdf</option> transformation generates output in Portable Document Format.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>PDF
<index-see-also>transformations</index-see-also></indexterm>
<indexterm>transformations
<indexterm>PDF</indexterm></indexterm>
<indexterm>PDF
<indexterm>plug-in, history of</indexterm></indexterm>
<indexterm>plug-ins
<indexterm>dita2pdf</indexterm></indexterm>
<indexterm>dita2pdf</indexterm>
</keywords>
</metadata>
</prolog>
<conbody>
<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>To run the PDF transformation, set the <parmname>transtype</parmname> parameter to <option>pdf</option>, or pass
the <parmname>--format</parmname>=<option>pdf</option> option to the <cmdname>dita</cmdname> command line.</p>
<codeblock><filepath conkeyref="conref-task/dita-cmd"/> <parmname>--input</parmname>=<varname
>input-file</varname> <parmname>--format</parmname>=<option>pdf</option></codeblock>
<p>where:</p>
<ul>
<li conkeyref="conref-task/novice-variables"/>
</ul>
</conbody>
</concept>

43
dita-ot-3.6/docsrc/topics/dita2xhtml.dita Normal file
View file

@ -0,0 +1,43 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<concept id="dita2xhtml">
<title>XHTML</title>
<shortdesc>The <option>xhtml</option> 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.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>languages
<indexterm>right-to-left</indexterm></indexterm>
<indexterm>transformations
<indexterm>XHTML</indexterm></indexterm>
<indexterm>XHTML
<index-see-also>transformations</index-see-also></indexterm>
<indexterm>HTML</indexterm>
<indexterm>plug-ins
<indexterm>dita2xhtml</indexterm></indexterm>
<indexterm>dita2xhtml</indexterm>
<indexterm>CSS
<indexterm>XHTML</indexterm></indexterm>
<indexterm>table of contents
<indexterm>XHTML</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<conbody>
<p>The XHTML output is always associated with the default DITA-OT CSS file (<filepath>commonltr.css</filepath> or
<filepath>commonrtl.css</filepath> for right-to-left languages). You can use toolkit parameters to add a custom
style sheet to override the default styles.</p>
<p>To run the XHTML transformation, set the <parmname>transtype</parmname> parameter to <option>xhtml</option>, or
pass the <parmname>--format</parmname>=<option>xhtml</option> option to the <cmdname>dita</cmdname> command
line.</p>
<codeblock><filepath conkeyref="conref-task/dita-cmd"/> <parmname>--input</parmname>=<varname
>input-file</varname> <parmname>--format</parmname>=<option>xhtml</option></codeblock>
<p>where:</p>
<ul>
<li conkeyref="conref-task/novice-variables"/>
</ul>
</conbody>
</concept>

55
dita-ot-3.6/docsrc/topics/enabling-debug-mode.dita Normal file
View file

@ -0,0 +1,55 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<task id="t-enabling-debug-mode">
<title>Enabling debug mode</title>
<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.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm><xmlelement>property</xmlelement></indexterm>
<indexterm>command line
<indexterm>debugging</indexterm></indexterm>
<indexterm><cmdname>dita</cmdname> command
<indexterm>debugging</indexterm></indexterm>
<indexterm>debugging
<indexterm>args.debug</indexterm></indexterm>
<indexterm>environment variables</indexterm>
<indexterm>stack trace</indexterm>
<indexterm>args.debug</indexterm>
<indexterm>Ant
<indexterm>args.debug</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<taskbody>
<steps>
<step>
<cmd>From the command prompt, add the following parameters:</cmd>
<choicetable>
<chhead>
<choptionhd>Application</choptionhd>
<chdeschd>Parameters</chdeschd>
</chhead>
<chrow>
<choption><cmdname>dita</cmdname> command</choption>
<chdesc><parmname>--debug</parmname>, <parmname>-debug</parmname>, or <parmname>-d</parmname></chdesc>
</chrow>
<chrow>
<choption>Ant</choption>
<chdesc><codeph>-v -Dargs.debug=yes</codeph></chdesc>
</chrow>
</choicetable>
<info>
<p>You also can add a <xmlelement>property</xmlelement> element to an Ant target in your build file, for
example: <codeblock outputclass="language-xml">&lt;property name="args.debug" value="yes"/></codeblock></p>
<note type="attention">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.</note>
</info>
</step>
</steps>
</taskbody>
</task>

844
dita-ot-3.6/docsrc/topics/error-messages-details.xml Normal file
View file

@ -0,0 +1,844 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<reference id="errormessages">
<title conkeyref="error-messages/title" conaction="pushreplace">DITA-OT error messages</title>
<shortdesc conkeyref="error-messages/shortdesc" conaction="pushreplace">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.</shortdesc>
<refbody>
<section id="overview" conkeyref="error-messages/overview" conaction="pushreplace">
<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>The toolkit uses the following severity scale:</p>
<dl id="severity-levels">
<dlentry>
<dt>Info (I)</dt>
<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>
</dlentry>
<dlentry>
<dt>Warning (W)</dt>
<dd>The toolkit encountered a problem that should be corrected. Processing will continue, but the output might
not be as expected.</dd>
</dlentry>
<dlentry>
<dt>Error (E)</dt>
<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>
</dlentry>
<dlentry>
<dt>Fatal (F)</dt>
<dd>The toolkit encountered a severe condition, processing stopped, and no output is generated.</dd>
</dlentry>
</dl>
<p>Plug-ins may be used to add additional messages to the toolkit; for more information, see
<xref keyref="rebuilding-docs"/>.</p>
</section>
<simpletable>
<sthead>
<stentry>Individual cells in this table may be used to push additional explanations for any existing error
message into the generated message topic.</stentry>
</sthead>
<strow>
<stentry>To add additional explanation to any message, add the explanation to this table in a single cell, and
set the following attributes on the <xmlelement>stentry</xmlelement> tag:
<ul>
<li><codeph>conkeyref="error-messages/MESSAGEID-extra"</codeph> -- for example, use the following to add
additional info to message DOTX001F: <codeph>conkeyref="error-messages/DOTX001F-extra"</codeph></li>
<li><codeph>conaction="pushreplace"</codeph></li>
</ul></stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTA001F-extra" conaction="pushreplace">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.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTA002F-extra" conaction="pushreplace">The input parameter was not
specified, so there is no DITA or DITAMAP file to transform. Ensure the parameter is set properly; see
<xref keyref="parameters-base">DITA-OT common parameters (args.input)</xref> if you are unsure how to specify
the input file.
<indexterm>DITA maps
<indexterm>input file</indexterm></indexterm>
</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTA003F-extra" conaction="pushreplace">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.
<indexterm>XSLT
<indexterm>stylesheet error</indexterm></indexterm></stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTA004F-extra" conaction="pushreplace">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.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTA006W-extra" conaction="pushreplace">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
<codeph>http://www.example.org/</codeph>). Absolute paths on the local file system will be broken if the
content is moved to a new system.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTA007E-extra" conaction="pushreplace">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.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTA008E-extra" conaction="pushreplace">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.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTA009E-extra" conaction="pushreplace">The running heading file, which
contains content to be added to the <xmlelement>head</xmlelement> 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.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTA066F-extra" conaction="pushreplace">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.</stentry>
</strow>
<strow>
<!-- This condition and the next belong to the org.dita.pdf2 plugin. Not sure if they should be moved below. -->
<stentry conkeyref="error-messages/DOTA067W-extra" conaction="pushreplace">According to the OASIS DITA
Specification, the <xmlelement>index-see</xmlelement> element should be ignored if the parent
<xmlelement>indexterm</xmlelement> contains other <xmlelement>indexterm</xmlelement> children.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTA068W-extra" conaction="pushreplace">According to the OASIS DITA
Specification, the <xmlelement>index-see-also</xmlelement> element should be ignored if the parent
<xmlelement>indexterm</xmlelement> contains other <xmlelement>indexterm</xmlelement> children.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTA069F-extra" conaction="pushreplace">Please ensure that the input file
path and file name were entered correctly.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTJ005F-extra" conaction="pushreplace"/>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTJ009E-extra" conaction="pushreplace">The transform was unable to create
files properly during the transform; results may not be as expected.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTJ012F-extra" conaction="pushreplace">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.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTJ013E-extra" conaction="pushreplace">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.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTJ014W-extra" conaction="pushreplace">An empty
<xmlelement>indexterm</xmlelement> element was found, and will appear in the index as ***. This index term
should be removed from the source.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTJ020W-extra" conaction="pushreplace">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.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTJ021W-extra" conaction="pushreplace">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.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTJ022F-extra" conaction="pushreplace">Either the input file or the ditaval
file should change, otherwise your build is explicitly excluding all content.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTJ023E-extra" conaction="pushreplace">Check whether the image exists in the
source location or already exists in the output directory.
<indexterm>image</indexterm>
</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTJ025E-extra" conaction="pushreplace">This message should only appear in
the following cases:
<ul>
<li>Errors earlier in the transform prevented this step of the transform from running; correct any errors
and try the build again.</li>
<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>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></stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTJ026E-extra" conaction="pushreplace">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
<xref keyref="dita-ot-issues"/>. </stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTJ028E-extra" conaction="pushreplace">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.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTJ029I-extra" conaction="pushreplace">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.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTJ030I-extra" conaction="pushreplace">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.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTJ031I-extra" conaction="pushreplace">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.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTJ033E-extra" conaction="pushreplace"/>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTJ034F-extra" conaction="pushreplace">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.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTJ035F-extra" conaction="pushreplace">This will appear when a topic is
outside the scope of the map; for example, if the main input map references
<filepath>"../other-directory/some.dita"</filepath>. The result would cause an output file to be created
outside of the output directory. See
<xref keyref="parameters-base">DITA-OT common parameters (outer.control and generate.copy.outer)</xref> for
details.
<indexterm>generate.copy.outer</indexterm>
</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTJ036W-extra" conaction="pushreplace">This will appear when a topic is
outside the scope of the map; for example, if the main input map references
<filepath>"../other-directory/some.dita"</filepath>. 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
<xref keyref="parameters-base">DITA-OT common parameters (outer.control and generate.copy.outer)</xref> for
details.
<indexterm>generate.copy.outer</indexterm></stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTJ037W-extra" conaction="pushreplace">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.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTJ038E-extra" conaction="pushreplace">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.
<indexterm>metadata
<indexterm>specialization error</indexterm></indexterm>
</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTJ039E-extra" conaction="pushreplace">Please see the topic on
<xref
href="http://docs.oasis-open.org/dita/dita/v1.3/os/part1-base/langRef/attributes/theconactionattribute.html#theconactionattribute"
format="html"
scope="external"
>Conref Push</xref> in the DITA specification for details on expected syntax
for this function.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTJ040E-extra" conaction="pushreplace">Please see the topic on
<xref
href="http://docs.oasis-open.org/dita/dita/v1.3/os/part1-base/langRef/attributes/theconactionattribute.html#theconactionattribute"
format="html"
scope="external"
>Conref Push</xref> in the DITA specification for details on expected syntax
for this function.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTJ041E-extra" conaction="pushreplace">The conref attribute must be a URI
reference to a DITA element. Please see the topic on
<xref
href="http://docs.oasis-open.org/dita/dita/v1.3/os/part1-base/archSpec/base/uri-based-addressing.html#uri-based-addressing"
format="html"
scope="external"
>URI-based addressing</xref> in the DITA specification for details on the
expected syntax.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTJ042E-extra" conaction="pushreplace">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
<xref
href="http://docs.oasis-open.org/dita/dita/v1.3/os/part1-base/langRef/attributes/theconactionattribute.html#theconactionattribute"
format="html"
scope="external"
>Conref Push</xref> in the DITA specification for more information about the
conref push "replace" function.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTJ043W-extra" conaction="pushreplace">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
<xref
href="http://docs.oasis-open.org/dita/dita/v1.3/os/part1-base/archSpec/base/uri-based-addressing.html#uri-based-addressing"
format="html"
scope="external"
>URI-based addressing</xref> 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.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTJ044W-extra" conaction="pushreplace">Please see the topic on
<xref
href="http://docs.oasis-open.org/dita/dita/v1.3/os/part1-base/langRef/attributes/theconactionattribute.html#theconactionattribute"
format="html"
scope="external"
>Conref Push</xref> in the DITA specification for details on expected syntax
for this function.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTJ045I-extra" conaction="pushreplace">This informational message is
intended to help you catch catch duplicate key definitions; if the keys are defined as expected, no action is
needed.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTJ046E-extra" conaction="pushreplace">See
<xref
href="http://docs.oasis-open.org/dita/dita/v1.3/os/part1-base/langRef/attributes/theconkeyrefattribute.html#theconkeyrefattribute"
format="html"
scope="external"
>the conkeyref definition</xref> for details on expected syntax and
usage.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTJ047I-extra" conaction="pushreplace">This message is intended to help you
locate incorrectly specified keys; if the key was specified correctly, this message may be ignored.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTJ049W-extra" conaction="pushreplace">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.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTJ050W-extra" conaction="pushreplace">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 <i>always</i> loaded into Eclipse with another plug-in that defines otherEntry
as an index term.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTJ051E-extra" conaction="pushreplace">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>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
<xref keyref="parameters-base">DITA-OT common parameters (outer.control and generate.copy.outer)</xref> for
details.
<indexterm>generate.copy.outer</indexterm></p></stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTJ052E-extra" conaction="pushreplace">DITA-OT supports a special syntax on
coderef elements to specify the character set of the target document. See
<xref keyref="extended-functionality"/> for details on the expected syntax.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTJ053W-extra" conaction="pushreplace">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.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTJ054E-extra" conaction="pushreplace">This message indicates that the
<xmlatt>href</xmlatt> value specified in <varname>%1</varname> does not use proper URI syntax. This may
occur when <xmlatt>href</xmlatt> includes characters that should be escaped (such as the space character,
which should be <codeph>%20</codeph> 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 <varname>%2</varname>.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTJ068E-extra" conaction="pushreplace">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.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTJ069E-extra" conaction="pushreplace">
<p>A circular reference was found in key definitions: a series of key references where the last key references
the first.</p>
<p>This may occur if a <xmlelement>topicref</xmlelement> element contains both a key name in the
<xmlatt>keys</xmlatt> attribute and a reference to the same key in the <xmlatt>keyref</xmlatt> attribute,
or if a <xmlatt>keyref</xmlatt> attribute points to a key that refers back to the referencing element.</p>
<p>To resolve this issue, change the target of the <xmlatt>keyref</xmlatt> so the key is defined by pointing
to a resource other than itself.</p>
</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTJ070I-extra" conaction="pushreplace">
<p>When a <xmlatt>class</xmlatt> attribute does not use the expected syntax, this usually indicates that
<xmlatt>class</xmlatt> 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>If this is a non-DITA element, it needs to be placed inside a <xmlelement>foreign</xmlelement> element so
that is not validated against DITA rules.
<indexterm>validate</indexterm>
</p>
</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTJ071E-extra" conaction="pushreplace">
<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
‘<codeph>;</codeph>’ on Windows, or colon ‘<codeph>:</codeph>’ on macOS or Linux).</p>
</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX001W-extra" conaction="pushreplace">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 <varname>%1</varname> 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.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX002W-extra" conaction="pushreplace">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.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX003I-extra" conaction="pushreplace">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).
<indexterm>table of contents
<indexterm>Eclipse Help</indexterm></indexterm>
</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX004I-extra" conaction="pushreplace">Eclipse builds use DITA’s
<xmlelement>navref</xmlelement> element to pull in other Eclipse TOC files. The build found a
<xmlelement>navref</xmlelement> element that does not reference any other file; the element will be
ignored.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX005E-extra" conaction="pushreplace">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.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX006E-extra" conaction="pushreplace">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").</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX007I-extra" conaction="pushreplace">The HTML Help compiler will only
include some types of information in the compiled CHM file; the current reference will not be
included.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX008E-extra" conaction="pushreplace">Ensure that the file exists and can
be read. <ph conkeyref="error-messages-details/changeExtension"/></stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX008W-extra" conaction="pushreplace">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. <ph
conkeyref="error-messages-details/changeExtension"
/>
<indexterm>table of contents
<indexterm>navigation title</indexterm></indexterm>
<indexterm>table of contents
<indexterm>DOTX008W</indexterm></indexterm>
</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX009W-extra" conaction="pushreplace">No title was found in the specified
topic, so the table of contents will use the indicated fallback value for this topic.
<indexterm>table of contents
<indexterm>DOTX009W</indexterm></indexterm>
<indexterm>table of contents
<indexterm>no title</indexterm></indexterm>
</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX010E-extra" conaction="pushreplace">The conref attribute must be a URI
reference to an existing DITA element. Please see the topic on
<xref
href="http://docs.oasis-open.org/dita/dita/v1.3/os/part1-base/archSpec/base/uri-based-addressing.html#uri-based-addressing"
format="html"
scope="external"
>URI-based addressing</xref> in the DITA specification for details on the
expected syntax. <ph id="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.</ph>
<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></stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX011W-extra" conaction="pushreplace">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.
<ph conkeyref="error-messages-details/changeExtension"/></stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX012W-extra" conaction="pushreplace">This message is deprecated and should
no longer appear in any logs.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX013E-extra" conaction="pushreplace">This may appear if (for example) you
have a <xmlelement>ph</xmlelement> 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. <ph
conkeyref="error-messages-details/changeExtension"
/></stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX014E-extra" conaction="pushreplace">The conref attribute must be a URI
reference to a DITA element. Please see the topic on
<xref
href="http://docs.oasis-open.org/dita/dita/v1.3/os/part1-base/archSpec/base/uri-based-addressing.html#uri-based-addressing"
format="html"
scope="external"
>URI-based addressing</xref> in the DITA specification for details on the
expected syntax.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX015E-extra" conaction="pushreplace">The conref attribute must be a URI
reference to a DITA element. Please see the topic on
<xref
href="http://docs.oasis-open.org/dita/dita/v1.3/os/part1-base/archSpec/base/uri-based-addressing.html#uri-based-addressing"
format="html"
scope="external"
>URI-based addressing</xref> in the DITA specification for details on the
expected syntax. <ph conkeyref="error-messages-details/changeExtension"/></stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX016W-extra" conaction="pushreplace">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.
<ph conkeyref="error-messages-details/changeExtension"/></stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX017E-extra" conaction="pushreplace">Found a value such as &lt;xref
href="">link text&lt;/xref>. 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.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX018I-extra" conaction="pushreplace">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.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX019W-extra" conaction="pushreplace">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.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX020E-extra" conaction="pushreplace">DITA-OT is only able to dynamically
retrieve titles when the target is a local (not peer or external) DITA resource.
<indexterm>navtitle</indexterm>
</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX021E-extra" conaction="pushreplace">DITA-OT is only able to dynamically
retrieve titles when the target is a local DITA resource.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX022W-extra" conaction="pushreplace">The build was unable to get a title
from the referenced topic; instead, a navigation title will be created based on the specified
<xmlelement>linktext</xmlelement> element inside of <xmlelement>topicmeta</xmlelement>.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX023W-extra" conaction="pushreplace">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.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX024E-extra" conaction="pushreplace">DITA-OT is only able to dynamically
retrieve titles and link text when the target is a local (not peer or external) DITA resource.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX025E-extra" conaction="pushreplace">DITA-OT is only able to dynamically
retrieve titles when the target is a local DITA resource.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX026W-extra" conaction="pushreplace">The referenc to this document did not
specify any link text for generated map-based links; the navigation title will be used as fallback.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX027W-extra" conaction="pushreplace">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.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX028E-extra" conaction="pushreplace">The link or cross reference has no
target specified and will not generate a link.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX029I-extra" conaction="pushreplace">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.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX030W-extra" conaction="pushreplace">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.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX031E-extra" conaction="pushreplace">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.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX032E-extra" conaction="pushreplace">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.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX033E-extra" conaction="pushreplace">An <xmlelement>xref</xmlelement>
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.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX034E-extra" conaction="pushreplace">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.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX035E-extra" conaction="pushreplace">An <xmlelement>xref</xmlelement>
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.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX036E-extra" conaction="pushreplace">An <xmlelement>xref</xmlelement>
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</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX037W-extra" conaction="pushreplace">No title was found for the current
document, so the HTML output file will set the <xmlelement>title</xmlelement> to "***". This value generally
appears in the title bar at the top of a browser.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX038I-extra" conaction="pushreplace">The <xmlelement>object</xmlelement>
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
<xmlelement>param</xmlelement> element inside the object.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX039W-extra" conaction="pushreplace">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.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX040I-extra" conaction="pushreplace">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.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX041W-extra" conaction="pushreplace">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.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX042I-extra" conaction="pushreplace">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.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX043I-extra" conaction="pushreplace">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 <xmlelement>reltable</xmlelement> in a DITA map will have the role attribute set to "friend".
<indexterm><xmlelement>reltable</xmlelement>
<index-see-also>relationship tables</index-see-also></indexterm>
</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX044E-extra" conaction="pushreplace">The <xmlelement>area</xmlelement>
element in an image map must provide a link target for the specified area. Please add an
<xmlelement>xref</xmlelement> element as a child of <xmlelement>area</xmlelement> and ensure that it
specifies a link target.
<indexterm>image map</indexterm></stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX045W-extra" conaction="pushreplace">Cross reference text inside the
<xmlelement>area</xmlelement> 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.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX046W-extra" conaction="pushreplace">The specified value was passed as-is
through to the <xmlelement>area</xmlelement> element in the HTML.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX047W-extra" conaction="pushreplace">The area element is intended to
define a region in an image map; coordinates must be specified in order to define that region.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX048I-extra" conaction="pushreplace">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.
<indexterm>table of contents
<indexterm>HTML Help</indexterm></indexterm>
</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX049I-extra" conaction="pushreplace">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.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX050W-extra" conaction="pushreplace">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.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX052W-extra" conaction="pushreplace">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.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX053E-extra" conaction="pushreplace">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.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX054W-extra" conaction="pushreplace">This will occur when a DITAVAL file
contains multiple styling rules that apply to the same element.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX055W-extra" conaction="pushreplace">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.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX056W-extra" conaction="pushreplace">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
<xref keyref="parameters-base">onlytopic.in.map</xref> parameter was specified. Be aware that the path
information above may not match the link in your topic.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX057W-extra" conaction="pushreplace">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.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX058W-extra" conaction="pushreplace">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).</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX060W-extra" conaction="pushreplace">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.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX061W-extra" conaction="pushreplace">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 <xmlelement>xref</xmlelement> or similar)
inside of a topic. For details, see the href attribute description in the OASIS standard’s definition of the
<xref
href="http://docs.oasis-open.org/dita/v1.2/os/spec/langref/topicref.html"
format="html"
scope="external"
>topicref element</xref>.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX063W-extra" conaction="pushreplace">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.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX064W-extra" conaction="pushreplace">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.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX065W-extra" conaction="pushreplace">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.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX066W-extra" conaction="pushreplace">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.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX067E-extra" conaction="pushreplace">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 <varname>%1</varname> 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.</stentry>
</strow>
</simpletable>
<section>
<title>Additional explanation for messages in the <filepath>org.dita.pdf2</filepath> plugin</title>
<simpletable>
<strow>
<stentry conkeyref="error-messages/PDFJ002E-extra" conaction="pushreplace">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.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/PDFJ003I-extra" conaction="pushreplace">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.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/PDFX011E-extra" conaction="pushreplace">Found an
<xmlelement>index-see</xmlelement> element as a child of a term that also exists as a standalone index
term, or as a term that also uses <xmlelement>index-see-also</xmlelement>. When using
<xmlelement>index-see</xmlelement> with an index term, that term should not be used to create page
references and should not reference additional terms. Treating the <xmlelement>index-see</xmlelement> as
<xmlelement>index-see-also</xmlelement>.</stentry>
</strow>
<strow>
<stentry conkeyref="error-messages/DOTX072I-extra" conaction="pushreplace">
<indexterm>navtitle</indexterm></stentry>
</strow>
</simpletable>
</section>
</refbody>
</reference>

26
dita-ot-3.6/docsrc/topics/error-messages.xml Normal file
View file

File diff suppressed because one or more lines are too long

331
dita-ot-3.6/docsrc/topics/globalization-languages.dita Normal file
View file

@ -0,0 +1,331 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<reference id="dita-globalization-languages">
<title>Supported languages</title>
<shortdesc>The following languages are supported for all PDF, XHTML, and HTML5-based transformation types.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm><xmlatt>xml:lang</xmlatt></indexterm>
<indexterm>Arabic</indexterm>
<indexterm>Bosnian</indexterm>
<indexterm>Belarusian</indexterm>
<indexterm>Bulgarian</indexterm>
<indexterm>Catalan</indexterm>
<indexterm>Chinese</indexterm>
<indexterm>Croatian</indexterm>
<indexterm>Czech</indexterm>
<indexterm>Danish</indexterm>
<indexterm>Dutch</indexterm>
<indexterm>English</indexterm>
<indexterm>Estonian</indexterm>
<indexterm>Finnish</indexterm>
<indexterm>French</indexterm>
<indexterm>German</indexterm>
<indexterm>Greek</indexterm>
<indexterm>Hebrew</indexterm>
<indexterm>Hungarian</indexterm>
<indexterm>Hindi</indexterm>
<indexterm>Icelandic</indexterm>
<indexterm>Indonesian</indexterm>
<indexterm>Italian</indexterm>
<indexterm>Japanese</indexterm>
<indexterm>Kazakh</indexterm>
<indexterm>Korean</indexterm>
<indexterm>Latvian</indexterm>
<indexterm>Lithuanian</indexterm>
<indexterm>Malay</indexterm>
<indexterm>Montenegrin</indexterm>
<indexterm>Norwegian</indexterm>
<indexterm>Polish</indexterm>
<indexterm>Portuguese</indexterm>
<indexterm>Romanian</indexterm>
<indexterm>Russian</indexterm>
<indexterm>Serbian</indexterm>
<indexterm>Slovak</indexterm>
<indexterm>Slovenian</indexterm>
<indexterm>Spanish</indexterm>
<indexterm>Swedish</indexterm>
<indexterm>Thai</indexterm>
<indexterm>Turkish</indexterm>
<indexterm>Ukrainian</indexterm>
<indexterm>Urdu</indexterm>
<indexterm>Vietnamese</indexterm>
<indexterm>languages
<indexterm>supported, list of</indexterm></indexterm>
<indexterm>language codes</indexterm>
<indexterm>strings</indexterm>
<indexterm>generated text</indexterm>
<indexterm>index
<indexterm>sorting</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<refbody>
<refsyn>
<note>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 <xmlatt>xml:lang</xmlatt>
attribute.</note>
</refsyn>
<table outputclass="table-hover" frame="none" colsep="0" rowsep="1">
<title>Supported languages</title>
<tgroup cols="3">
<colspec colwidth="3*" colname="language"/>
<colspec colwidth="2*" colname="code"/>
<colspec colwidth="5*" colname="notes"/>
<thead>
<row>
<entry>Language</entry>
<entry>Language&#xA0;code</entry>
<entry>Notes</entry>
</row>
</thead>
<tbody>
<row>
<entry><ph xml:lang="ar">العربية</ph> (Arabic)</entry>
<entry>ar or ar-EG</entry>
<entry>Defaults to right-to-left presentation.</entry>
</row>
<row>
<entry><ph xml:lang="be">Беларуская</ph> (Belarusian)</entry>
<entry>be or be-BY</entry>
<entry/>
</row>
<row>
<entry><ph xml:lang="bs">Bosanski</ph> (Bosnian)</entry>
<entry>bs or bs-BA</entry>
<entry/>
</row>
<row>
<entry><ph xml:lang="bg">Български</ph> (Bulgarian)</entry>
<entry>bg or bg-BG</entry>
<entry/>
</row>
<row>
<entry><ph xml:lang="ca">Català</ph> (Catalan)</entry>
<entry>ca-ES</entry>
<entry/>
</row>
<row>
<entry><ph xml:lang="zh-CN">简体中文</ph> (Simplified Chinese)</entry>
<entry>zh-CN or zh-Hans</entry>
<entry>PDF index is not properly collated by default.</entry>
</row>
<row>
<entry><ph xml:lang="zh-TW">繁體中文</ph> (Traditional Chinese)</entry>
<entry>zh-TW or zh-Hant</entry>
<entry>PDF index is not properly collated by default.</entry>
</row>
<row>
<entry><ph xml:lang="hr">Hrvatski</ph> (Croatian)</entry>
<entry>hr or hr-HR</entry>
<entry/>
</row>
<row>
<entry><ph xml:lang="cs">Čeština</ph> (Czech)</entry>
<entry>cs or cs-CZ</entry>
<entry/>
</row>
<row>
<entry><ph xml:lang="da">Dansk</ph> (Danish)</entry>
<entry>da or da-DK</entry>
<entry/>
</row>
<row>
<entry><ph xml:lang="nl">Nederlands</ph> (Dutch)</entry>
<entry>nl or nl-NL</entry>
<entry>Subset of generated text also available for Belgian Dutch (nl-BE)</entry>
</row>
<row>
<entry>English (US)</entry>
<entry>en or en-US</entry>
<entry>Subset of generated text also available for British English (en-GB) and Canadian English
(en-CA)</entry>
</row>
<row>
<entry><ph xml:lang="et">Eesti</ph> (Estonian)</entry>
<entry>et or et-EE</entry>
<entry/>
</row>
<row>
<entry><ph xml:lang="fi">Suomi</ph> (Finnish)</entry>
<entry>fi or fi-FI</entry>
<entry/>
</row>
<row>
<entry><ph xml:lang="fr">Français</ph> (French)</entry>
<entry>fr or fr-FR</entry>
<entry>Subset of generated text also available for Belgian French (fr-BE), Canadian French (fr-CA), and
Swiss French (fr-CH)</entry>
</row>
<row>
<entry><ph xml:lang="de">Deutsch</ph> (German)</entry>
<entry>de or de-DE</entry>
<entry>Subset of generated text also available for Swiss German (de-CH)</entry>
</row>
<row>
<entry><ph xml:lang="el">Ελληνικά</ph> (Greek)</entry>
<entry>el or el-GR</entry>
<entry/>
</row>
<row>
<entry><ph xml:lang="he">עברית</ph> (Hebrew)</entry>
<entry>he or he-IL</entry>
<entry>Defaults to right-to-left presentation.</entry>
</row>
<row>
<entry><ph xml:lang="hi">हिन्दी</ph> (Hindi)</entry>
<entry>hi or hi-HI</entry>
<entry/>
</row>
<row>
<entry><ph xml:lang="hu">Magyar</ph> (Hungarian)</entry>
<entry>hu or hu-HU</entry>
<entry/>
</row>
<row>
<entry><ph xml:lang="is">Íslenska</ph> (Icelandic)</entry>
<entry>is or is-IS</entry>
<entry/>
</row>
<row>
<entry><ph xml:lang="id">Bahasa Indonesia</ph> (Indonesian)</entry>
<entry>id or id-ID</entry>
<entry/>
</row>
<row>
<entry><ph xml:lang="it">Italiano</ph> (Italian)</entry>
<entry>it or it-IT</entry>
<entry>Subset of generated text also available for Swiss Italian (it-CH)</entry>
</row>
<row>
<entry><ph xml:lang="ja">日本語</ph> (Japanese)</entry>
<entry>ja or ja-JP</entry>
<entry>PDF index is not properly collated by default.</entry>
</row>
<row>
<entry><ph xml:lang="kk">Қазақша</ph> (Kazakh)</entry>
<entry>kk or kk-KZ</entry>
<entry/>
</row>
<row>
<entry><ph xml:lang="ko">한국어</ph> (Korean)</entry>
<entry>ko or ko-KR</entry>
<entry/>
</row>
<row>
<entry><ph xml:lang="lv">Latviešu</ph> (Latvian)</entry>
<entry>lv or lv-LV</entry>
<entry/>
</row>
<row>
<entry><ph xml:lang="lt">Lietuvių</ph> (Lithuanian)</entry>
<entry>lt or lt-LT</entry>
<entry/>
</row>
<row>
<entry><ph xml:lang="mk">Македонски</ph> (Macedonian)</entry>
<entry>mk or mk-MK</entry>
<entry/>
</row>
<row>
<entry><ph xml:lang="ms">Bahasa Melayu</ph> (Malay)</entry>
<entry>ms or ms-MY</entry>
<entry/>
</row>
<row>
<entry><ph xml:lang="sr-Latn-ME">Crnogorski</ph> (Montenegrin)</entry>
<entry>sr-Latn-ME</entry>
<entry/>
</row>
<row>
<entry><ph xml:lang="no">Norsk</ph> (Norwegian)</entry>
<entry>no or no-NO</entry>
<entry/>
</row>
<row>
<entry><ph xml:lang="pl">Polski</ph> (Polish)</entry>
<entry>pl or pl-PL</entry>
<entry/>
</row>
<row>
<entry><ph xml:lang="pt">Português</ph> (Portuguese)</entry>
<entry>pt or pt-PT</entry>
<entry/>
</row>
<row>
<entry><ph xml:lang="pt-BR">Português do Brasil</ph> (Brazilian Portuguese)</entry>
<entry>pt-BR</entry>
<entry/>
</row>
<row>
<entry><ph xml:lang="ro">Română</ph> (Romanian)</entry>
<entry>ro or ro-RO</entry>
<entry/>
</row>
<row>
<entry><ph xml:lang="ru">Русский</ph> (Russian)</entry>
<entry>ru or ru-RU</entry>
<entry/>
</row>
<row>
<entry><ph xml:lang="sr">Српски</ph> (Serbian - Cyrillic script)</entry>
<entry>sr, sr-CS, sr-RS, or sr-SP</entry>
<entry/>
</row>
<row>
<entry><ph xml:lang="sr-Latn-RS">Srpski</ph> (Serbian - Latin script)</entry>
<entry>sr-Latn-RS</entry>
<entry/>
</row>
<row>
<entry><ph xml:lang="sk">Slovenčina</ph> (Slovak)</entry>
<entry>sk or sk-SK</entry>
<entry/>
</row>
<row>
<entry><ph xml:lang="sl">Slovenščina</ph> (Slovenian)</entry>
<entry>sl or sl-SI</entry>
<entry/>
</row>
<row>
<entry><ph xml:lang="es">Español</ph> (Spanish)</entry>
<entry>es or es-ES</entry>
<entry>Also supported using es-419 (Latin American Spanish).</entry>
</row>
<row>
<entry><ph xml:lang="sv">Svenska</ph> (Swedish)</entry>
<entry>sv or sv-SE</entry>
<entry/>
</row>
<row>
<entry><ph xml:lang="th">ภาษาไทย</ph> (Thai)</entry>
<entry>th or th-TH</entry>
<entry/>
</row>
<row>
<entry><ph xml:lang="tr">Türkçe</ph> (Turkish)</entry>
<entry>tr or tr-TR</entry>
<entry/>
</row>
<row>
<entry><ph xml:lang="uk">Українська</ph> (Ukrainian)</entry>
<entry>uk or uk-UA</entry>
<entry/>
</row>
<row>
<entry><ph xml:lang="ur">اردو</ph> (Urdu)</entry>
<entry>ur or ur-PK</entry>
<entry>Defaults to right-to-left presentation.</entry>
</row>
<row>
<entry><ph xml:lang="vi">Tiếng Việt</ph> (Vietnamese)</entry>
<entry>vi or vi-VN</entry>
<entry/>
</row>
</tbody>
</tgroup>
</table>
</refbody>
</reference>

67
dita-ot-3.6/docsrc/topics/globalization-support.dita Normal file
View file

@ -0,0 +1,67 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<concept id="globalization-support">
<title>Globalization support</title>
<titlealts>
<navtitle>Globalization support</navtitle>
</titlealts>
<shortdesc>DITA Open Toolkit offers globalization support in the following areas: generated text, index sorting, and
bi-directional text.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm><xmlatt>dir</xmlatt></indexterm>
<indexterm><xmlatt>index:lang</xmlatt></indexterm>
<indexterm>languages
<indexterm>index sorting</indexterm></indexterm>
<indexterm>languages
<indexterm>right-to-left</indexterm></indexterm>
<indexterm>languages
<indexterm>bi-directional</indexterm></indexterm>
<indexterm>English</indexterm>
<indexterm>strings</indexterm>
<indexterm>index
<indexterm>sorting</indexterm></indexterm>
<indexterm>bi-directional languages</indexterm>
<indexterm>generated text</indexterm>
<indexterm>CSS
<indexterm>bi-directional languages</indexterm>
<indexterm>right-to-left languages</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<conbody>
<p>
<dl>
<dlentry>
<dt>Generated text</dt>
<dd><term>Generated text</term> 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>
<li>The word "Chapter" in a PDF file.</li>
<li>The phrases "Related concepts," "Related tasks," and "Related reference" in HTML output.</li>
</ul></dd>
</dlentry>
<dlentry>
<dt>Index sorting</dt>
<dd>DITA-OT can use only a single language to sort indexes.<draft-comment
author="Kristen James Eberlein"
time="11 August 2012"
>What does the ICU for Java provide? Does index sorting occur if ICU for Java is NOT
installed?</draft-comment></dd>
</dlentry>
<dlentry>
<dt>Bi-directional text</dt>
<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 <xmlatt>dir</xmlatt> attribute can be used to override the default rendering direction.</dd>
</dlentry>
</dl>When DITA-OT generates output, it takes the first value for the <xmlatt>xml:lang</xmlatt> 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 <xmlatt>xml:lang</xmlatt> attribute is found, the toolkit defaults
to U.S. English. You can use the
<xref href="../parameters/configuration-properties.dita">configuration.properties</xref> to change the default
language.</p>
</conbody>
</concept>

24
dita-ot-3.6/docsrc/topics/globalization.dita Normal file
View file

@ -0,0 +1,24 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<task id="dita-globalization">
<title>Globalizing DITA content</title>
<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
<xmlatt>xml:lang</xmlatt> and <xmlatt>dir</xmlatt> attributes that are set in the source content to provide
globalization support. You can create custom plug-ins to support additional languages.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm><xmlatt>dir</xmlatt></indexterm>
<indexterm><xmlatt>index:lang</xmlatt></indexterm>
<indexterm>languages
<indexterm>supported</indexterm></indexterm>
<indexterm>translating</indexterm>
<indexterm>localizing</indexterm>
<indexterm>globalizing</indexterm>
<indexterm>strings</indexterm>
</keywords>
</metadata>
</prolog>
</task>

11
dita-ot-3.6/docsrc/topics/globalizing.ditamap Normal file
View file

@ -0,0 +1,11 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<map>
<title>Globalizing DITA content</title>
<topicref keyref="globalization">
<topicref keyref="globalization-support"/>
<topicref keyref="plugin-addgeneratedtext"/>
<topicref keyref="globalization-languages"/>
</topicref>
</map>

70
dita-ot-3.6/docsrc/topics/html-customization-css.dita Normal file
View file

@ -0,0 +1,70 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<task id="custom-html-css">
<title>Adding custom CSS</title>
<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.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>cascading style sheet
<index-see>CSS</index-see></indexterm>
<indexterm>CSS
<indexterm>adding custom</indexterm></indexterm>
<indexterm>HTML
<indexterm>CSS</indexterm></indexterm>
<indexterm>HTML5
<indexterm>CSS</indexterm></indexterm>
<indexterm>transformations
<indexterm>HTML5</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<taskbody>
<context>
<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>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>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></context>
<steps>
<step>
<cmd>Create a custom CSS file and store it in your project along with your DITA source files.</cmd>
<stepxmp>
<note>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 <filepath>docsrc/resources/dita-ot-doc.css</filepath>.</note>
</stepxmp>
</step>
<step>
<cmd>Set the <parmname>args.css</parmname> parameter to the name of your custom CSS file.</cmd>
<info>
<p>The value of this parameter should be only the file name. You can specify the absolute path to the file
with <parmname>args.cssroot</parmname>.</p></info>
</step>
<step>
<cmd>Set the <parmname>args.copycss</parmname> parameter to <option>yes</option>.</cmd>
<info>
<p>This setting ensures that your custom CSS file will be copied to the output directory.</p></info>
</step>
<step>
<cmd>Set <parmname
>args.cssroot</parmname> to the absolute path of the folder that contains your custom CSS file.</cmd>
</step>
<step importance="optional">
<cmd>Set <parmname>args.csspath</parmname> to specify the location of the CSS file in the output folder.</cmd>
<info>
<p>If <parmname>args.csspath</parmname> 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 <filepath>css</filepath>, set
<parmname>args.csspath</parmname> to <option>css</option>.</p></info>
</step>
</steps>
<result>
<note type="tip">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 <filepath>doc/index.html</filepath>.</note>
</result>
</taskbody>
</task>

75
dita-ot-3.6/docsrc/topics/html-customization-header.dita Normal file
View file

@ -0,0 +1,75 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<task id="custom-html-header">
<title>Adding custom headers and footers</title>
<titlealts>
<navtitle>Headers and footers</navtitle>
</titlealts>
<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.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm><xmlelement>header</xmlelement></indexterm>
<indexterm><xmlelement>footer</xmlelement></indexterm>
<indexterm><xmlelement>div</xmlelement>
<indexterm>HTML header</indexterm>
<indexterm>HTML footer</indexterm></indexterm>
<indexterm><xmlatt>role</xmlatt></indexterm>
<indexterm>HTML5
<indexterm>headers</indexterm></indexterm>
<indexterm>HTML5
<indexterm>footers</indexterm></indexterm>
<indexterm>CSS
<indexterm>adding custom</indexterm></indexterm>
<indexterm>CSS
<indexterm>HTML5</indexterm></indexterm>
<indexterm>HTML5
<indexterm>CSS</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<taskbody>
<context>
<p>In HTML5 output, the contents of the header file will be wrapped in an HTML5 <xmlelement>header</xmlelement>
element with the <xmlatt>role</xmlatt> attribute set to <option>banner</option>. The footer file contents are
wrapped in an HTML5 <xmlelement>footer</xmlelement> element with the <xmlatt>role</xmlatt> attribute set to
<option>contentinfo</option>.</p>
<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>
<p><codeblock outputclass="language-xml normalize-space show-line-numbers show-whitespace"><coderef
href="../resources/header.xml"
/></codeblock>
</p>
<note>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 <xmlelement>div</xmlelement> element.</note>
</context>
<steps>
<step>
<cmd>Set <parmname>args.hdr</parmname> to include an XML file as a running header that appears above the page
content.</cmd>
<info> </info>
</step>
<step>
<cmd>Set <parmname>args.ftr</parmname> to include an XML file as a running footer that appears below the page
content.</cmd>
</step>
<step importance="optional">
<cmd>Add custom CSS rules to style headers and/or footers.</cmd>
<info>
<p>For example, the DITA-OT documentation stylesheet includes the following header rules: </p>
<p><codeblock outputclass="language-css normalize-space show-line-numbers show-whitespace"><coderef
href="../resources/dita-ot-doc.css#token=header-coderef,end-header-ref"
/></codeblock>
</p>
</info>
</step>
</steps>
<result>
<note type="tip">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 <filepath>doc/index.html</filepath>.</note>
</result>
</taskbody>
</task>

67
dita-ot-3.6/docsrc/topics/html-customization-navigation.dita Normal file
View file

@ -0,0 +1,67 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<task id="custom-html-navigation">
<title>Adding navigation to topics</title>
<titlealts>
<navtitle>Adding navigation</navtitle>
</titlealts>
<shortdesc>In HTML5 output, you can set a parameter to include table-of-contents navigation in the
<xmlelement>nav</xmlelement> element of each page. The navigation can be rendered in a sidebar or menu via
CSS.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm><xmlelement>nav</xmlelement></indexterm>
<indexterm>HTML5
<indexterm>navigation, adding</indexterm></indexterm>
<indexterm>transformations
<indexterm>HTML5</indexterm></indexterm>
<indexterm>CSS
<indexterm>adding custom</indexterm></indexterm>
<indexterm>nav-toc</indexterm>
<indexterm>HTML5
<indexterm>nav-toc</indexterm></indexterm>
<indexterm>table of contents
<indexterm>HTML5</indexterm></indexterm>
<indexterm>table of contents
<indexterm>nav-toc</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<taskbody>
<context>
<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>As of DITA-OT 2.2, the <parmname>nav-toc</parmname> parameter can be used in HTML5 transformations to embed
navigation directly in topics using native HTML5 elements without JavaScript or framesets.</p>
</context>
<steps>
<step>
<cmd>Set the <parmname>nav-toc</parmname> parameter to one of the following options:</cmd>
<choices>
<choice>The <option>partial</option> 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).</choice>
<choice>The <option>full</option> option embeds the complete navigation for the entire map in each
topic.</choice>
</choices>
</step>
<step importance="optional">
<cmd>Add custom CSS rules to style the navigation.</cmd>
<info>
<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>
<p>
<codeblock outputclass="language-css normalize-space show-line-numbers show-whitespace"><coderef
href="../resources/dita-ot-doc.css#token=nav-coderef,end-nav-ref"
/></codeblock>
</p>
</info>
</step>
</steps>
<result>
<note type="tip">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 <filepath>doc/index.html</filepath>.</note>
</result>
</taskbody>
</task>

20
dita-ot-3.6/docsrc/topics/html-customization-parameters.dita Normal file
View file

@ -0,0 +1,20 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<task id="custom-html-parameters">
<title>Setting parameters for custom HTML</title>
<titlealts>
<navtitle>Setting HTML parameters</navtitle>
</titlealts>
<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.)</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>HTML
<indexterm>parameters</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
</task>

132
dita-ot-3.6/docsrc/topics/html-customization-plugin-bundle-css.dita Normal file
View file

@ -0,0 +1,132 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<task id="custom-html-plugin-bundle-css">
<title>Bundling CSS in a custom HTML plug-in</title>
<titlealts>
<navtitle>Bundling custom CSS</navtitle>
</titlealts>
<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.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm><xmlelement>require</xmlelement></indexterm>
<indexterm>HTML
<indexterm>custom plug-in</indexterm></indexterm>
<indexterm>HTML
<indexterm>CSS</indexterm></indexterm>
<indexterm>CSS
<indexterm>HTML transforms</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<taskbody>
<context>
<p>This scenario walks through the process of creating a very simple plug-in
(<codeph>com.example.html5-custom-css</codeph>) that creates a new transformation type:
<option>html5-custom-css</option>. </p>
<p>The <option>html5-custom-css</option> 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>
<li>
<p>Specify the <filepath>css</filepath> subfolder of the plug-in as the source directory for custom CSS with
<parmname>args.cssroot</parmname>.</p></li>
<li>
<p>Specify the name of the custom CSS file with <parmname>args.css</parmname>.</p>
<p>The value of this parameter tells DITA-OT to use the <filepath>custom.css</filepath> file provided by the
plug-in.</p></li>
<li>
<p>Ensure that the CSS file is copied to the output directory by setting <parmname>args.copycss</parmname> to
<option>yes</option>.</p></li>
<li>
<p>Set the destination path for CSS files in the output folder with <parmname>args.csspath</parmname>.</p>
<p>CSS files are copied to the root level of the output folder by default. Setting this parameter places CSS
files in a dedicated <filepath>css</filepath> subfolder.</p></li>
</ul>
<p>All four parameters are set in the Ant script (<filepath>build_html5-custom-css.xml</filepath>).</p>
</context>
<steps>
<step>
<cmd>In the <filepath>plugins</filepath> directory, create a directory named
<filepath>com.example.html5-custom-css</filepath>.</cmd>
</step>
<step>
<cmd>In the new <filepath>com.example.html5-custom-css</filepath> directory, create a plug-in configuration file
(<filepath>plugin.xml</filepath>) that declares the new <option>html5-custom-css</option> transformation and
its dependencies.</cmd>
<stepxmp>
<fig>
<title>Sample <filepath>plugin.xml</filepath> file</title>
<codeblock outputclass="language-xml normalize-space show-line-numbers show-whitespace"><coderef
href="../samples/plugins/com.example.html5-custom-css/plugin.xml"
/></codeblock>
</fig>
<note>This plug-in will extend the default HTML5 transformation, so the <xmlelement>require</xmlelement>
element explicitly defines <filepath>org.dita.html5</filepath> as a dependency.</note>
</stepxmp>
</step>
<step>
<cmd>In the <filepath>com.example.html5-custom-css</filepath> directory, create a subdirectory named
<filepath>css</filepath>.</cmd>
</step>
<step>
<cmd>In the new <filepath>css</filepath> subdirectory, create a file named <filepath>custom.css</filepath> with
your custom CSS rules.</cmd>
<stepxmp>
<fig>
<title>Sample <filepath>custom.css</filepath> file</title>
<codeblock outputclass="language-css normalize-space show-line-numbers show-whitespace"><coderef
href="../samples/plugins/com.example.html5-custom-css/css/custom.css"
/></codeblock>
</fig>
<note type="tip">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.</note>
</stepxmp>
</step>
<step>
<cmd>In the <filepath>com.example.html5-custom-css</filepath> root directory, add an Ant script
(<filepath>build_html5-custom-css.xml</filepath>) to define the transformation type.</cmd>
<stepxmp>
<fig>
<title>Sample build file: <filepath>build_html5-custom-css.xml</filepath></title>
<codeblock outputclass="language-xml normalize-space show-line-numbers show-whitespace"><coderef
href="../samples/plugins/com.example.html5-custom-css/build_html5-custom-css.xml"
/></codeblock>
</fig>
</stepxmp>
</step>
</steps>
<result>
<note type="tip">The files for this sample plug-in are included in the DITA-OT installation directory under
<filepath>docsrc/samples/plugins/com.example.html5-custom-css/</filepath> and on
<xref
href="https://github.com/dita-ot/docs/tree/develop/samples/plugins/com.example.html5-custom-css"
format="html"
scope="external"
>GitHub</xref>.</note>
<p>The plug-in directory has the following layout and files:</p>
<codeblock>com.example.html5-custom-css
├── build_html5-custom-css.xml
├── css
│   └── custom.css
└── plugin.xml</codeblock>
</result>
<postreq>
<ol>
<li>Run <filepath conkeyref="conref-task/dita-cmd"/>
<parmname>--install</parmname> to install the plug-in and make the <option>html5-custom-css</option>
transformation available.</li>
<li>Build output with the new transformation type to verify that the plug-in works as intended.
<codeblock><filepath conkeyref="conref-task/dita-cmd"/> <parmname>--input</parmname>=<varname
>my.ditamap</varname> <parmname>--format</parmname>=<option>html5-custom-css</option></codeblock>
</li>
<li>Refine the styles in your <filepath>custom.css</filepath> file as necessary.</li>
</ol>
</postreq>
</taskbody>
</task>

122
dita-ot-3.6/docsrc/topics/html-customization-plugin-javascript.dita Normal file
View file

@ -0,0 +1,122 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<task id="custom-html-plugin-webfont">
<title>Inserting JavaScript in generated HTML</title>
<titlealts>
<navtitle>Inserting JavaScript</navtitle>
</titlealts>
<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.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm><xmlelement>footer</xmlelement></indexterm>
<indexterm><xmlelement>require</xmlelement></indexterm>
<indexterm><xmlelement>head</xmlelement></indexterm>
<indexterm>HTML5
<indexterm>JavaScript, adding</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<taskbody>
<context>
<p>This scenario walks through the process of creating a very simple plug-in
(<codeph>com.example.html5-javascript</codeph>) that creates a new transformation type:
<option>html5-javascript</option>. </p>
<p>The <option>html5-javascript</option> transformation includes a custom page footer file with a JavaScript
tracking snippet and sets the <parmname>args.ftr</parmname> parameter to integrate the script content in the
HTML5 <xmlelement>footer</xmlelement> element of the generated pages.</p>
<note>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.</note>
</context>
<steps>
<step>
<cmd>In the <filepath>plugins</filepath> directory, create a directory named
<filepath>com.example.html5-javascript</filepath>.</cmd>
</step>
<step>
<cmd>In the new <filepath>com.example.html5-javascript</filepath> directory, create a plug-in configuration file
(<filepath>plugin.xml</filepath>) that declares the new <option>html5-javascript</option> transformation and
its dependencies.</cmd>
<stepxmp>
<fig>
<title>Sample <filepath>plugin.xml</filepath> file</title>
<codeblock outputclass="language-xml normalize-space show-line-numbers show-whitespace"><coderef
href="../samples/plugins/com.example.html5-javascript/plugin.xml"
/></codeblock>
</fig>
<note>This plug-in will extend the default HTML5 transformation, so the <xmlelement>require</xmlelement>
element explicitly defines <filepath>org.dita.html5</filepath> as a dependency.</note>
</stepxmp>
</step>
<step>
<cmd>In the <filepath>com.example.html5-javascript</filepath> directory, create a subdirectory named
<filepath>include</filepath>.</cmd>
</step>
<step>
<cmd>In the new <filepath>include</filepath> subdirectory, create a file named
<filepath>javascript.ftr.xml</filepath> with your custom JavaScript code.</cmd>
<stepxmp>
<fig>
<title>Sample <filepath>javascript.ftr.xml</filepath> file</title>
<codeblock outputclass="language-javascript normalize-space show-line-numbers show-whitespace"><coderef
href="../samples/plugins/com.example.html5-javascript/include/javascript.ftr.xml"
/></codeblock>
</fig>
<p>The division wrapper will be discarded when generating HTML files, and the contents will be inserted into
the <xmlelement>footer</xmlelement> element of each page.</p>
</stepxmp>
</step>
<step>
<cmd>In the <filepath>com.example.html5-javascript</filepath> root directory, add an Ant script
(<filepath>build_html5-javascript.xml</filepath>) to define the transformation type and set the path to the
JavaScript footer file created in the previous step.</cmd>
<stepxmp>
<fig>
<title>Sample build file: <filepath>build_html5-javascript.xml</filepath></title>
<codeblock outputclass="language-xml normalize-space show-line-numbers show-whitespace"><coderef
href="../samples/plugins/com.example.html5-javascript/build_html5-javascript.xml"
/></codeblock>
</fig>
</stepxmp>
</step>
</steps>
<result>
<note type="tip">The files for this sample plug-in are included in the DITA-OT installation directory under
<filepath>docsrc/samples/plugins/com.example.html5-javascript/</filepath> and on
<xref
href="https://github.com/dita-ot/docs/tree/develop/samples/plugins/com.example.html5-javascript"
format="html"
scope="external"
>GitHub</xref>.</note>
<p>The plug-in directory has the following layout and files:</p>
<codeblock>com.example.html5-javascript
├── build_html5-javascript.xml
├── include
│   └── javascript.ftr.xml
└── plugin.xml</codeblock>
</result>
<postreq>
<ol>
<li>Run <filepath conkeyref="conref-task/dita-cmd"/>
<parmname>--install</parmname> to install the plug-in and make the <option>html5-javascript</option>
transformation available.</li>
<li>Build output with the new transformation type to verify that the plug-in works as intended.
<codeblock><filepath conkeyref="conref-task/dita-cmd"/> <parmname>--input</parmname>=<varname
>my.ditamap</varname> <parmname>--format</parmname>=<option>html5-javascript</option></codeblock></li>
<li>Open one of the generated HTML topic files in a modern web browser and check the JavaScript
<uicontrol>Console</uicontrol>. When the page is loaded, <msgph>Adding Google Analytics tracker</msgph> will
appear on the console to verify that the sample script is loaded.</li>
<li>Remove the <codeph>console.log</codeph> debugging message from the sample JavaScript code, and replace the
<codeph>'UA-XXXXX-Y'</codeph> placeholder string with the tracking ID of the Google Analytics property you
wish to track.</li>
</ol>
<note type="tip">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 <codeph>async</codeph> script attribute, you may prefer to insert the
JavaScript snippet in the <xmlelement>head</xmlelement> element of the generated HTML files using the
<parmname>args.hdf</parmname> parameter instead.</note>
</postreq>
</taskbody>
</task>

165
dita-ot-3.6/docsrc/topics/html-customization-plugin-webfont.dita Normal file
View file

@ -0,0 +1,165 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<task id="custom-html-plugin-webfont">
<title>Embedding web fonts in HTML output</title>
<titlealts>
<navtitle>Embedding web fonts</navtitle>
</titlealts>
<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.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm><xmlelement>require</xmlelement></indexterm>
<indexterm><xmlelement>link</xmlelement></indexterm>
<indexterm><xmlelement>head</xmlelement></indexterm>
<indexterm>HTML
<indexterm>custom plug-in</indexterm></indexterm>
<indexterm>HTML
<indexterm>fonts</indexterm></indexterm>
<indexterm>CSS
<indexterm>web fonts</indexterm></indexterm>
<indexterm>fonts
<indexterm>HTML</indexterm></indexterm>
<indexterm>web fonts
<index-see>fonts</index-see></indexterm>
<indexterm>custom.css</indexterm>
<indexterm>build_html5-webfont.xml</indexterm>
<indexterm>plugin.xml</indexterm>
<indexterm>org.dita.html5</indexterm>
</keywords>
</metadata>
</prolog>
<taskbody>
<context>
<p>This scenario walks through the process of creating a very simple plug-in
(<codeph>com.example.html5-webfont</codeph>) that creates a new transformation type:
<option>html5-webfont</option>. </p>
<p>The <option>html5-webfont</option> 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>
<li>
<p>Specify a file that links to the font from the document head with <parmname>args.hdf</parmname>.</p></li>
<li>
<p>Specify the <filepath>css</filepath> subfolder of the plug-in as the source directory for custom CSS with
<parmname>args.cssroot</parmname>.</p></li>
<li>
<p>Specify the name of the custom CSS file with <parmname>args.css</parmname>.</p>
<p>The value of this parameter tells DITA-OT to use the <filepath>custom.css</filepath> file provided by the
plug-in.</p></li>
<li>
<p>Ensure that the CSS file is copied to the output directory by setting <parmname>args.copycss</parmname> to
<option>yes</option>.</p></li>
<li>
<p>Set the destination path for CSS files in the output folder with <parmname>args.csspath</parmname>.</p>
<p>CSS files are copied to the root level of the output folder by default. Setting this parameter places CSS
files in a dedicated <filepath>css</filepath> subfolder.</p></li>
</ul>
<p>All five parameters are set in the Ant script (<filepath>build_html5-webfont.xml</filepath>).</p>
</context>
<steps>
<step>
<cmd>In the <filepath>plugins</filepath> directory, create a directory named
<filepath>com.example.html5-webfont</filepath>.</cmd>
</step>
<step>
<cmd>In the new <filepath>com.example.html5-webfont</filepath> directory, create a plug-in configuration file
(<filepath>plugin.xml</filepath>) that declares the new <option>html5-webfont</option> transformation and
its dependencies.</cmd>
<stepxmp>
<fig>
<title>Sample <filepath>plugin.xml</filepath> file</title>
<codeblock outputclass="language-xml normalize-space show-line-numbers show-whitespace"><coderef
href="../samples/plugins/com.example.html5-webfont/plugin.xml"
/></codeblock>
</fig>
<note>This plug-in will extend the default HTML5 transformation, so the <xmlelement>require</xmlelement>
element explicitly defines <filepath>org.dita.html5</filepath> as a dependency.</note>
</stepxmp>
</step>
<step>
<cmd>In the <filepath>com.example.html5-webfont</filepath> directory, create a subdirectory named
<filepath>include</filepath>.</cmd>
</step>
<step>
<cmd>In the new <filepath>include</filepath> subdirectory, create a file named
<filepath>webfont.hdf.xml</filepath> with your custom font links.</cmd>
<stepxmp>
<fig>
<title>Sample <filepath>webfont.hdf.xml</filepath> file</title>
<codeblock outputclass="language-xml normalize-space show-line-numbers show-whitespace"><coderef
href="../samples/plugins/com.example.html5-webfont/include/webfont.hdf.xml"
/></codeblock>
</fig>
<p>This example uses the
<xref keyref="noto-sans-font"/> font. You can use multiple fonts by creating additional
<xmlelement>link</xmlelement> references in this file. The division wrapper will be discarded when
generating HTML files, and the contents will be inserted into the <xmlelement>head</xmlelement> element of
each page.</p>
</stepxmp>
</step>
<step>
<cmd>In the <filepath>com.example.html5-webfont</filepath> directory, create a subdirectory named
<filepath>css</filepath>.</cmd>
</step>
<step>
<cmd>In the new <filepath>css</filepath> subdirectory, create a file named <filepath>custom.css</filepath> with
the stylesheet rules that apply the custom <codeph>font-family</codeph> to the desired elements.</cmd>
<stepxmp>
<fig>
<title>Sample <filepath>custom.css</filepath> file</title>
<codeblock outputclass="language-css normalize-space show-line-numbers show-whitespace"><coderef
href="../samples/plugins/com.example.html5-webfont/css/custom.css"
/></codeblock>
</fig>
<p>This example uses
<xref keyref="noto-sans-font"/> 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>
</stepxmp>
</step>
<step>
<cmd>In the <filepath>com.example.html5-webfont</filepath> root directory, add an Ant script
(<filepath>build_html5-webfont.xml</filepath>) to define the transformation type.</cmd>
<stepxmp>
<fig>
<title>Sample build file: <filepath>build_html5-webfont.xml</filepath></title>
<codeblock outputclass="language-xml normalize-space show-line-numbers show-whitespace"><coderef
href="../samples/plugins/com.example.html5-webfont/build_html5-webfont.xml"
/></codeblock>
</fig>
</stepxmp>
</step>
</steps>
<result>
<note type="tip">The files for this sample plug-in are included in the DITA-OT installation directory under
<filepath>docsrc/samples/plugins/com.example.html5-webfont/</filepath> and on
<xref
href="https://github.com/dita-ot/docs/tree/develop/samples/plugins/com.example.html5-webfont"
format="html"
scope="external"
>GitHub</xref>.</note>
<p>The plug-in directory has the following layout and files:</p>
<codeblock>com.example.html5-webfont
├── build_html5-webfont.xml
├── css
│   └── custom.css
├── include
│   └── webfont.hdf.xml
└── plugin.xml</codeblock>
</result>
<postreq>
<ol>
<li>Run <filepath conkeyref="conref-task/dita-cmd"/>
<parmname>--install</parmname> to install the plug-in and make the <option>html5-webfont</option>
transformation available.</li>
<li>Build output with the new transformation type to verify that the plug-in works as intended.
<codeblock><filepath conkeyref="conref-task/dita-cmd"/> <parmname>--input</parmname>=<varname
>my.ditamap</varname> <parmname>--format</parmname>=<option>html5-webfont</option></codeblock>
</li>
<li>Refine the styles in your <filepath>custom.css</filepath> file to adjust the font usage as necessary.</li>
</ol>
</postreq>
</taskbody>
</task>

33
dita-ot-3.6/docsrc/topics/html-customization-plugins.dita Normal file
View file

@ -0,0 +1,33 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<concept id="custom-html-plugins">
<title>Custom HTML plug-ins</title>
<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.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>HTML
<indexterm>custom plug-in</indexterm></indexterm>
<indexterm>HTML
<indexterm>fonts</indexterm></indexterm>
<indexterm>HTML
<indexterm>JavaScript</indexterm></indexterm>
<indexterm>HTML
<indexterm>CSS</indexterm></indexterm>
<indexterm>HTML
<indexterm>markup, adding</indexterm></indexterm>
<indexterm>CSS
<indexterm>HTML</indexterm></indexterm>
<indexterm>fonts
<indexterm>HTML</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<conbody>
<note>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.</note>
</conbody>
</concept>

63
dita-ot-3.6/docsrc/topics/html-customization-properties-file.dita Normal file
View file

@ -0,0 +1,63 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<task id="custom-html-properties-file">
<title>Customizing HTML with a <filepath>.properties</filepath> file</title>
<titlealts>
<navtitle>Using a properties file</navtitle>
</titlealts>
<shortdesc>You can also use a <filepath>.properties</filepath> file to reference a set of build parameters when
building output with the <cmdname>dita</cmdname> command. The DITA-OT documentation uses a
<filepath>.properties</filepath> file to include custom CSS, header branding, and table-of-contents navigation in
the HTML5 output.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm><cmdname>dita</cmdname> command
<indexterm>.properties file</indexterm></indexterm>
<indexterm>HTML
<indexterm>build properties</indexterm></indexterm>
<indexterm>CSS
<indexterm>.properties file</indexterm></indexterm>
<indexterm>.properties file</indexterm>
</keywords>
</metadata>
</prolog>
<taskbody>
<steps>
<step>
<cmd>Create a <filepath>.properties</filepath> file to store the parameter settings for your
customization.</cmd>
<info>
<note type="tip">You can use one of the sample <filepath>.properties</filepath> files from the DITA-OT
documentation as a starting point for your own customizations. These files are available in the installation
folder under <filepath>docsrc/samples/properties/</filepath>.</note>
</info>
<stepxmp>
<p>For example:</p>
<fig>
<title>The <filepath>docsrc/samples/properties/sequence-html5.properties</filepath> file</title>
<codeblock outputclass="language-properties normalize-space show-line-numbers show-whitespace"><coderef
href="../samples/properties/sequence-html5.properties"
/></codeblock>
</fig>
</stepxmp>
</step>
<step>
<cmd>Reference your <filepath>.properties</filepath> file with the <cmdname>dita</cmdname> command when building
your output.</cmd>
<stepxmp>
<codeblock outputclass="syntax-bash"><cmdname>dita</cmdname> <parmname>--input</parmname>=<varname
>my.ditamap</varname> <parmname>--format</parmname>=<option>html5</option> <parmname
>--propertyfile</parmname>=<varname>my.properties</varname></codeblock>
</stepxmp>
<info/>
</step>
</steps>
<result>
<note>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 <filepath>doc/index.html</filepath>.</note>
</result>
</taskbody>
</task>

23
dita-ot-3.6/docsrc/topics/html-customization.dita Normal file
View file

@ -0,0 +1,23 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<task id="customizing-html-output">
<title>Customizing HTML output</title>
<titlealts>
<navtitle>Customizing HTML</navtitle>
</titlealts>
<shortdesc>You can <ph id="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</ph>.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>HTML
<indexterm>customizing</indexterm></indexterm>
<indexterm>transformations
<indexterm>HTML</indexterm></indexterm>
<indexterm>plug-ins
<indexterm>HTML5</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
</task>

26
dita-ot-3.6/docsrc/topics/html-customization.ditamap Normal file
View file

@ -0,0 +1,26 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<map>
<title>Customizing HTML output</title>
<topicref keyref="html-customization-parameters" collection-type="family">
<topicref keyref="html-customization-navigation"/>
<topicref keyref="html-customization-css"/>
<topicref keyref="html-customization-header"/>
<topicref keyref="generate-copy-outer"/>
</topicref>
<topicref keyref="html-customization-properties-file"/>
<reltable>
<title>Bi-directional links</title>
<relrow>
<relcell>
<topicref keyref="html-customization"/>
<topicref keyref="plugin-coding-conventions"/>
</relcell>
<relcell>
<topicref keyref="html-customization-plugins"/>
</relcell>
</relrow>
</reltable>
</map>

102
dita-ot-3.6/docsrc/topics/implement-saxon-collation-uri-resolvers.dita Normal file
View file

@ -0,0 +1,102 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<topic id="implement-saxon-collation-uri-resolvers">
<title>Implementing custom Saxon collation URI resolvers</title>
<titlealts>
<navtitle>Custom collation URI resolvers</navtitle>
</titlealts>
<shortdesc>Plug-ins can provide custom URI resolvers that provide collators for specific collation URIs.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>Saxon
<indexterm><xmlelement>service</xmlelement></indexterm></indexterm>
<indexterm>Ant
<indexterm><xmlelement>jar</xmlelement></indexterm></indexterm>
<indexterm><xmlatt>xsl:sort</xmlatt></indexterm>
<indexterm>Chinese</indexterm>
<indexterm>I18N
<indexterm>plug-in</indexterm></indexterm>
<indexterm>XSLT
<indexterm>URI resolver</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<body>
<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>For example, the DITA Community I18N plugin provides a custom collator for doing dictionary-based sorting and
grouping of Simplified Chinese. </p>
<p>To allow multiple plug-ins to contribute collation URI resolvers, DITA-OT defines a superinterface of Saxon’s
<codeph>CollationUriResolver</codeph> interface,
<codeph>org.dita.dost.module.saxon.DelegatingCollationUriResolver</codeph>, that takes a base resolver.</p>
<p>Implementations of <codeph>DelegatingCollationUriResolver</codeph> 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>
<note>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.</note>
<p>A typical delegating collation URI resolver looks like
this:<codeblock
outputclass="language-java"
>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 */
}</codeblock></p>
<p>To implement a custom collation URI resolver:
<ol>
<li>Add your plugin’s JAR file in the DITA-OT class path as described in
<xref keyref="plugin-javalib"/>.</li>
<li>Implement an instance of <codeph>org.dita.dost.module.saxon.DelegatingCollationUriResolver</codeph> as
described above.</li>
<li>Include a file named <filepath>org.dita.dost.module.saxon.DelegatingCollationUriResolver</filepath> in the
directory <filepath>META-INF/services</filepath> in the compiled JAR that your plug-in provides. Each line of
the file must be the name of a class that implements
<codeph>org.dita.dost.module.saxon.DelegatingCollationUriResolver</codeph>:<codeblock
>org.example.i18n.saxon.MyCollationUriResolver</codeblock>
<p>You can create the services file using <xmlelement>service</xmlelement> elements in an Ant
<xmlelement>jar</xmlelement>
task:<codeblock outputclass="language-xml">&lt;jar destfile="${basedir}/target/lib/example-saxon.jar">
⋮
&lt;service type="org.dita.dost.module.saxon.DelegatingCollationUriResolver">
&lt;provider classname="org.example.i18n.saxon.MyCollationUriResolver"/>
&lt;/service>
⋮
&lt;/jar></codeblock></p></li>
<li>To use the collator in XSLT style sheets, specify the collation URI on <xmlatt>xsl:sort</xmlatt> elements
(or anywhere a collator URI can be
specified):<codeblock outputclass="language-xml">&lt;xsl:apply-templates select="word">
&lt;xsl:sort collation="http://org.example.i18n.MyCollator"/>
&lt;/xsl:apply-templates></codeblock></li>
</ol></p>
</body>
</topic>

71
dita-ot-3.6/docsrc/topics/implement-saxon-customizations.dita Normal file
View file

@ -0,0 +1,71 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<topic id="implement-saxon-customizations">
<title>Adding Saxon customizations</title>
<titlealts>
<navtitle>Saxon customizations</navtitle>
</titlealts>
<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
<xmlelement>pipeline</xmlelement> task with custom XSLT.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>Saxon
<indexterm><xmlelement>service</xmlelement></indexterm></indexterm>
<indexterm>Ant
<indexterm><xmlelement>jar</xmlelement></indexterm></indexterm>
<indexterm>Ant
<indexterm><xmlelement>pipeline</xmlelement></indexterm></indexterm>
<indexterm>Ant
<indexterm><xmlelement>xslt</xmlelement></indexterm></indexterm>
<indexterm>Saxon
<index-see-also>Ant</index-see-also></indexterm>
<indexterm>Ant
<index-see-also>Saxon</index-see-also></indexterm>
<indexterm>I18N
<indexterm>plug-in</indexterm></indexterm>
<indexterm>plug-ins
<indexterm>Saxon</indexterm></indexterm>
<indexterm>XSLT
<indexterm>Saxon</indexterm></indexterm>
<indexterm>preprocessing
<indexterm>extension points, Saxon</indexterm></indexterm>
<indexterm>Java
<indexterm>ServiceLoader</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<body>
<p>Plug-ins can provide the following Saxon extensions:
<ul>
<li>Extension functions</li>
<li>Collation URI resolvers</li>
</ul></p>
<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
<filepath>META-INF/services</filepath> directory in plug-in-provided JAR files.</p>
<p>You can create the file manually or generate it dynamically using <xmlelement>service</xmlelement> elements in
Ant <xmlelement>jar</xmlelement> tasks. See the topics for the different extension types for details.</p>
<p>These extensions use the DITA Open Toolkit Ant <xmlelement>pipeline</xmlelement> element to wrap
<xmlelement>xslt</xmlelement> elements. You can do this in plug-ins as shown in this excerpt from the DITA
Community I18N plugin’s <filepath>build.xml</filepath>
file:<codeblock outputclass="language-xml">&lt;target name="org.dita-community.i18n-saxon-extension-test">
&lt;pipeline message="Test the DITA Community i18n Saxon extension functions"
taskname="i18n-extension-function-test">
&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"
>
&lt;/xslt>
&lt;/pipeline>
&lt;/target></codeblock></p>
<p>Normal XSLT extensions to built-in transformation types will automatically have the extensions available to
them.</p>
<p>The dynamic Saxon configuration is implemented in the class <codeph>org.dita.dost.module.XsltModule</codeph>,
which backs the <xmlelement>pipeline</xmlelement>/<xmlelement>xslt</xmlelement> element.</p>
<p> </p>
</body>
</topic>

63
dita-ot-3.6/docsrc/topics/implement-saxon-extension-functions.dita Normal file
View file

@ -0,0 +1,63 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<topic id="implement-saxon-extension-functions">
<title>Implementing Saxon extension functions</title>
<titlealts>
<navtitle>Saxon extensions</navtitle>
</titlealts>
<shortdesc>Plug-ins can contribute Saxon extension functions for use in XSLT transformations run by DITA Open
Toolkit.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>Saxon
<indexterm><xmlelement>service</xmlelement></indexterm></indexterm>
<indexterm>Ant
<indexterm><xmlelement>jar</xmlelement></indexterm></indexterm>
<indexterm>XSLT
<indexterm>Saxon</indexterm></indexterm>
<indexterm>Java
<indexterm>extension functions</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<body>
<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>
<p>To implement extension functions, you must do the following:
<ol>
<li>Add your plug-in’s JAR file in the DITA-OT class path as described in
<xref keyref="plugin-javalib"/>.</li>
<li>For each function, implement a class that extends
<codeph>net.sf.saxon.lib.ExtensionFunctionDefinition</codeph>. This class provides the namespace name and
function name for the function as well as details about its arguments and so on. See
<xref keyref="saxon-java-extensions-impl"/> in the Saxon documentation.</li>
<li>Include a file named <filepath>net.sf.saxon.lib.ExtensionFunctionDefinition</filepath> in the directory
<filepath>META-INF/services</filepath> in the compiled JAR that your plug-in provides. Each line of the file
must be the name of a class that implements <codeph
>net.sf.saxon.lib.ExtensionFunctionDefinition</codeph>: <codeblock>com.example.saxon.functions.Add
com.example.saxon.functions.Substract</codeblock>
<p>You can create the file using <xmlelement>service</xmlelement> elements in an Ant
<xmlelement>jar</xmlelement>
task:<codeblock outputclass="language-xml">&lt;jar destfile="${basedir}/target/lib/example-saxon.jar">
⋮
&lt;service type="net.sf.saxon.lib.ExtensionFunctionDefinition">
&lt;provider classname="com.example.saxon.functions.Add"/>
&lt;provider classname="com.example.saxon.functions.Subtract"/>
&lt;/service>
⋮
&lt;/jar></codeblock></p></li>
<li>In your XSLT transformations, declare the namespace the functions are bound
to:<codeblock outputclass="language-xml">&lt;xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
<b>xmlns:eg="http://example.com/saxon-extensions"</b>
version="2.0"></codeblock></li>
</ol></p>
<p>You should then be able to use the extension functions as you would any other
function:<codeblock outputclass="language-xml">&lt;xsl:variable name="test" select="<b
>eg:add(1, 2)</b>"/></codeblock></p>
</body>
</topic>

66
dita-ot-3.6/docsrc/topics/increasing-the-jvm.dita Normal file
View file

@ -0,0 +1,66 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<task id="t-increasing-the-JVM">
<title>Increasing Java memory allocation</title>
<titlealts>
<navtitle>Increasing Java memory</navtitle>
</titlealts>
<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 <codeph>ANT_OPTS</codeph> environment variable.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>macOS
<indexterm>increase Java memory</indexterm></indexterm>
<indexterm>Linux
<indexterm>increase Java memory</indexterm></indexterm>
<indexterm>Windows
<indexterm>increase Java memory</indexterm></indexterm>
<indexterm>command line
<indexterm>increase Java memory</indexterm></indexterm>
<indexterm>operating system
<index-see>Linux</index-see>
<index-see>macOS</index-see>
<index-see>Windows</index-see></indexterm>
<indexterm>Java
<indexterm>memory</indexterm></indexterm>
<indexterm><codeph>ANT_OPTS</codeph></indexterm>
<indexterm>Java
<indexterm><codeph>ANT_OPTS</codeph></indexterm></indexterm>
<indexterm>metadata
<indexterm>processing time, effect on</indexterm></indexterm>
<indexterm>memory</indexterm>
</keywords>
</metadata>
</prolog>
<taskbody>
<steps-unordered>
<step>
<cmd>To change the value for a specific session, from the command prompt, issue the following command:</cmd>
<choicetable outputclass="multi-platform">
<chhead>
<choptionhd>Platform</choptionhd>
<chdeschd>Command</chdeschd>
</chhead>
<chrow platform="unix">
<choption>Linux or macOS&#xA0;</choption>
<chdesc><codeph>export ANT_OPTS=$ANT_OPTS -Xmx<varname>1024</varname>M</codeph></chdesc>
</chrow>
<chrow platform="windows">
<choption>Windows</choption>
<chdesc><codeph>set ANT_OPTS=%ANT_OPTS% -Xmx<varname>1024</varname>M</codeph></chdesc>
</chrow>
</choicetable>
<info>
<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></info>
</step>
<step>
<cmd>To persistently change the value, change the value allocated to the <codeph>ANT_OPTS</codeph> environment
variable on your system.</cmd>
</step>
</steps-unordered>
</taskbody>
</task>

29
dita-ot-3.6/docsrc/topics/input-formats.dita Normal file
View file

@ -0,0 +1,29 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<topic id="alternative-authoring-formats">
<title>Authoring formats</title>
<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.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>Lightweight DITA</indexterm>
<indexterm>LwDITA
<index-see>Lightweight DITA</index-see></indexterm>
<indexterm>MDITA
<index-see>Lightweight DITA</index-see></indexterm>
<indexterm>XDITA
<index-see>Lightweight DITA</index-see></indexterm>
<indexterm>HDITA
<index-see>Lightweight DITA</index-see></indexterm>
<indexterm>authoring formats</indexterm>
<indexterm>input formats
<index-see>authoring formats</index-see></indexterm>
<indexterm>formats
<index-see>authoring formats</index-see>
<index-see>transformations</index-see></indexterm>
</keywords>
</metadata>
</prolog>
</topic>

14
dita-ot-3.6/docsrc/topics/input-formats.ditamap Normal file
View file

@ -0,0 +1,14 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD LIGHTWEIGHT DITA Map//EN" "lw-map.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<map>
<topicmeta>
<navtitle>Input formats</navtitle>
</topicmeta>
<topicref keyref="dita-xml-input"/>
<topicref keyref="markdown-input"/>
<topicref keyref="lwdita-input"/>
<topicref keyref="markdown-dita-syntax-reference"/>
</map>

63
dita-ot-3.6/docsrc/topics/installing-client.dita Normal file
View file

@ -0,0 +1,63 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<task id="installing-client">
<title>Installing DITA Open Toolkit</title>
<titlealts>
<navtitle>Installing DITA-OT</navtitle>
</titlealts>
<shortdesc id="what-is-client">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.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>macOS
<indexterm>installing DITA-OT</indexterm></indexterm>
<indexterm>Linux
<indexterm>installing DITA-OT</indexterm></indexterm>
<indexterm>Windows
<indexterm>installing DITA-OT</indexterm></indexterm>
<indexterm><cmdname>dita</cmdname> command
<indexterm>installing</indexterm></indexterm>
<indexterm>installing
<indexterm>DITA-OT</indexterm></indexterm>
<indexterm>Java
<indexterm>Java Development Kit (JDK)</indexterm>
<indexterm>Java Runtime Environment (JRE)</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<taskbody>
<prereq>
<ul>
<li>
<p>Ensure that you have a Java Runtime Environment (JRE) or Java Development Kit (JDK).</p>
<p conkeyref="reusable-components/java-clients"/></li>
<li importance="optional" platform="windows">If you want to generate HTML Help, ensure that you have HTML Help
Workshop installed.
<p>You can download the Help Workshop from
<xref keyref="download.html-help-workshop"/>.</p></li>
</ul>
</prereq>
<steps>
<step>
<cmd><ph conkeyref="conref-task/download-ot"/></cmd>
</step>
<step>
<cmd>Extract the contents of the package to the directory where you want to install DITA-OT.</cmd>
</step>
<step>
<cmd>Add the absolute path for the <filepath>bin</filepath> folder of the DITA-OT installation directory to the
<xref keyref="PATH"/>.</cmd>
<stepresult>
<note id="dita-in-path" type="tip">This defines the necessary environment variable that allows the
<cmdname>dita</cmdname> command to be run from any location on the file system without typing the path to
the command.
<indexterm><cmdname>dita</cmdname> command
<indexterm>PATH environment variable</indexterm></indexterm>
</note>
</stepresult>
</step>
</steps>
</taskbody>
</task>

81
dita-ot-3.6/docsrc/topics/installing-via-homebrew.dita Normal file
View file

@ -0,0 +1,81 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<task id="installing-via-homebrew">
<title>Installing on macOS via Homebrew</title>
<titlealts>
<navtitle>Installing via Homebrew</navtitle>
</titlealts>
<shortdesc>An alternative installation method can be used to install DITA-OT on macOS via
<xref keyref="homebrew"/>, the platform’s most popular open-source package manager.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>macOS</indexterm>
<indexterm><cmdname>dita</cmdname> command
<indexterm>Homebrew</indexterm></indexterm>
<indexterm>installing
<indexterm>Homebrew</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<taskbody>
<prereq>
<p>The steps below assume you have already installed
<xref keyref="homebrew"/> according to the instructions at
<xref keyref="homebrew">brew.sh</xref>.</p>
<note type="tip">Verify that your
<xref keyref="PATH"/> begins with <filepath>/usr/local/bin</filepath> to ensure that Homebrew-installed software
takes precedence over any programs of the same name elsewhere on the system.</note>
</prereq>
<steps>
<step>
<cmd>Update Homebrew to make sure the latest package formulas are available on your system:</cmd>
<stepxmp><codeblock outputclass="syntax-bash">$ <cmdname>brew update</cmdname>
Already up-to-date.</codeblock></stepxmp>
<stepresult>
<p>Homebrew responds with a list of any new or updated formulæ.</p></stepresult>
</step>
<step importance="optional">
<cmd>Check the version of DITA-OT that is available from Homebrew:</cmd>
<stepxmp><codeblock outputclass="syntax-bash">$ <cmdname>brew info dita-ot</cmdname>
<systemoutput>dita-ot: stable <keyword keyref="maintenance-version"/>
DITA Open Toolkit is an implementation of the OASIS DITA specification
https://www.dita-ot.org/
/usr/local/Cellar/dita-ot/<keyword keyref="maintenance-version"/> (<varname>number of files</varname>, <varname
>package size</varname>) *
Built from source on <varname>YYYY-MM-DD</varname> at <varname>hh:mm:ss</varname>
From: https://github.com/Homebrew/homebrew-core/blob/master/Formula/dita-ot.rb
==> Requirements
Required: java >= 1.8 ✔</systemoutput>
</codeblock></stepxmp>
<stepresult>
<p>The version of the DITA-OT formula is shown, along with basic information on the package.</p></stepresult>
</step>
<step>
<cmd>Install the <codeph>dita-ot</codeph> package:</cmd>
<stepxmp><codeblock outputclass="syntax-bash">$ <cmdname>brew install dita-ot</cmdname>
<systemoutput>Downloading…</systemoutput></codeblock></stepxmp>
<stepresult>
<p>Homebrew will automatically download the latest version of the toolkit, install it in a subfolder of the
local package Cellar and symlink the <cmdname>dita</cmdname> command to
<filepath>/usr/local/bin/dita</filepath>.</p></stepresult>
</step>
<step importance="optional">
<cmd>Verify the installation:</cmd>
<stepxmp><codeblock outputclass="syntax-bash">$ <cmdname>which dita</cmdname>
<systemoutput>/usr/local/bin/dita</systemoutput></codeblock></stepxmp>
<stepresult>
<p>The response confirms that the system will use the Homebrew-installed version of DITA-OT.</p></stepresult>
</step>
<step importance="optional">
<cmd>Check the DITA-OT version number:</cmd>
<stepxmp><codeblock outputclass="syntax-bash">$ <cmdname>dita</cmdname> <parmname>--version</parmname>
<systemoutput>DITA-OT version <keyword keyref="maintenance-version"/></systemoutput></codeblock></stepxmp>
<stepresult>The DITA-OT version number appears on the console.</stepresult>
</step>
</steps>
<result>
<p>You can now run the <cmdname>dita</cmdname> command to transform DITA content.</p></result>
</taskbody>
</task>

25
dita-ot-3.6/docsrc/topics/installing.ditamap Normal file
View file

@ -0,0 +1,25 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<map>
<title>Installing</title>
<topicref keyref="prerequisite-software"/>
<topicref keyref="determining-version-of-ditaot"/>
<!-- prettier-ignore-start -->
<!-- ↓ branch-filter ↓ -->
<topicref href="using-dita-command.dita"
keys="first-build-using-dita-command" locktitle="yes">
<topicmeta>
<navtitle>Building output</navtitle>
</topicmeta>
<ditavalref href="../resources/novice.ditaval">
<ditavalmeta>
<dvrResourcePrefix>first-build-</dvrResourcePrefix>
</ditavalmeta>
</ditavalref>
</topicref>
<!-- ↑ end-filtering ↑ -->
<!-- prettier-ignore-end -->
<topicref keyref="installing-via-homebrew"/>
</map>

146
dita-ot-3.6/docsrc/topics/logging.dita Normal file
View file

@ -0,0 +1,146 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<concept id="loghandling">
<title>Logging build information</title>
<titlealts>
<navtitle>Logging</navtitle>
</titlealts>
<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.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>Apache FOP
<indexterm>log files</indexterm></indexterm>
<indexterm><cmdname>dita</cmdname> command
<indexterm>logging</indexterm></indexterm>
<indexterm>logging</indexterm>
<indexterm>verbose logging</indexterm>
<indexterm>Ant
<indexterm>logging</indexterm></indexterm>
<indexterm>debugging
<index-see-also>logging</index-see-also></indexterm>
<indexterm>Java
<indexterm>logging</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<conbody>
<p>The logging behavior varies depending on whether you use the <cmdname>dita</cmdname> command or Ant to invoke a
toolkit build.</p>
<dl>
<dlentry>
<dt><cmdname>dita</cmdname> command</dt>
<dd>
<p>By default, only warning and error messages are written to the screen.</p>
<ul>
<li>
<p>For more information, enable verbose logging with <cmdname>dita</cmdname>
<parmname>--verbose</parmname>.</p>
<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>
<p>To enable debug logging, use <cmdname>dita</cmdname>
<parmname>--debug</parmname>.</p>
<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>
<note type="attention">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.</note>
</li>
<li>
<p>To write the log to a file, use <cmdname>dita</cmdname>
<parmname>--logfile</parmname>=<varname>file</varname> and specify the path to the log file.</p>
<p>Unless an absolute path is specified, the value will be interpreted relative to the current
directory.</p></li>
</ul></dd>
</dlentry>
<dlentry>
<dt>Ant</dt>
<dd>By default, status information is written to the screen. If you issue the <parmname>-l</parmname> parameter,
the build runs silently and the information is written to a log file with the name and location that you
specified.</dd>
</dlentry>
</dl>
<section>
<title>Using other Ant loggers</title>
<p>You also can use other Ant loggers; see
<xref href="https://ant.apache.org/manual/listeners.html" format="html" scope="external">Listeners &amp;
Loggers</xref> in the Ant documentation for more information.</p>
<p>For example, you can use the <b>AnsiColorLogger</b> to colorize the messages written on the screen.</p>
<dl>
<dlentry>
<dt><cmdname>dita</cmdname> command</dt>
<dd>
<p>To use a custom Ant logger with the <cmdname>dita</cmdname> command, add the logger to the
<codeph>ANT_ARGS</codeph> environment variable by calling the following command before calling the
<cmdname>dita</cmdname> command:</p>
<codeblock
outputclass="syntax-bash"
>export ANT_ARGS="-logger org.apache.tools.ant.listener.AnsiColorLogger"</codeblock>
<p>Now you will get colorized messages when the <cmdname>dita</cmdname> command runs.</p>
<note type="tip">Environment variables can also be set permanently. See
<xref href="https://www.java.com/en/download/help/path.xml" format="html" scope="external">How do I set or
change the PATH system variable?</xref> for information on how to set the
<xref keyref="PATH"/>. You can set the <codeph>ANT_ARGS</codeph> environment variable in the same
way.</note>
</dd>
</dlentry>
<dlentry>
<dt>Ant</dt>
<dd>
<p>If you prefer to launch DITA-OT directly from Ant, you can also add the logger to the
<codeph>ANT_ARGS</codeph> environment variable, as explained above. You can also set the logger with the
<codeph>-logger</codeph> parameter when calling Ant.</p>
<codeblock outputclass="syntax-bash">ant -logger org.apache.tools.ant.listener.AnsiColorLogger</codeblock>
</dd>
</dlentry>
</dl>
</section>
<section>
<title>FOP debug logging</title>
<indexterm>logback.xml</indexterm>
<indexterm>classpath
<indexterm>logging</indexterm></indexterm>
<p>In PDF processing with <tm trademark="Apache" tmtype="tm">Apache</tm> 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>To enable debug logging, modify the <filepath>config/logback.xml</filepath> file or add your own
<filepath>logback.xml</filepath> to the classpath with a higher priority to override the default settings. For
more information, see the
<xref href="https://logback.qos.ch/manual/configuration.html" format="html" scope="external">Logback
configuration documentation</xref>.</p>
<note type="attention">Enabling FOP debug logging will dramatically increase the size of generated log
files.</note>
</section>
<!--<section><title>Analyze messages on the screen</title><p>During the building process, some information or messages
occur on the screen to tell you about the status, warnings, errors, or fatal errors. You need to analyze the
messages to solve the problems. <ul>
<li>If the build succeeded with some warning messages on the screen, it means that there are something
incorrect within the user input parameters or source DITA files; but you can still get the correct
output.</li>
<li>If the build succeeded with some error messages on the screen, it means that there are something incorrect
within the user input parameters or source DITA files; the output maybe not correct.</li>
<li>If the build failed with fatal error message on the screen, it means that there are something illegal or
invalid within the user input parameters or source DITA files; you may get no output, or wrong output.</li>
</ul>
</p></section>-->
<!--<section><title>Analyze messages in the log file</title><p>A log file in plain text format is generated in the log
directory, which has a name combined with both input file name and transformation type. You can open it and find more
detailed information, which are helpful for solving problems. You can use the same way introduced above to
analyze the messages and solve the problems.</p><p>The log directory can be specified by:</p><ul>
<li>using Ant, with argument <codeph>-logfile=<userinput>log-file</userinput></codeph></li>
<li>using command-line tool, the parameter <codeph>/logdir:<userinput>log-dir</userinput></codeph>.</li>
</ul></section>-->
<!--<section><title>Turn on debug mode</title><p>Under debug mode, diagnostic information, such as: environment
variables, stack trace, will be logged into the log file. These information can help the user or developer to go
deep into the problems and find the root cause.</p><p>By default, the debug mode is disabled. To turn on the
debug mode on, you need to follow the usage below: <ul>
<li>Append <codeph>-v</codeph> and <codeph>-Dargs.debug=yes</codeph> in Ant command.</li>
<li>Append <codeph>/d</codeph> or <codeph>/debug</codeph> in command-line tool.</li>
</ul></p></section>-->
</conbody>
</concept>

108
dita-ot-3.6/docsrc/topics/lwdita-input.dita Normal file
View file

@ -0,0 +1,108 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<topic id="lwdita-input">
<title>Preview support for Lightweight DITA</title>
<titlealts>
<navtitle>Lightweight DITA</navtitle>
</titlealts>
<shortdesc>DITA-OT provides preview support for the authoring formats proposed for
<xref keyref="lwdita"/>, or “<term>LwDITA</term>”. The XDITA, MDITA and HDITA formats are alternative
representations of DITA content in XML, Markdown and HTML5.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm><xmlelement>topicref</xmlelement></indexterm>
<indexterm><xmlatt>format</xmlatt></indexterm>
<indexterm>authoring formats
<indexterm>Lightweight DITA</indexterm></indexterm>
<indexterm>metadata
<indexterm>Lightweight DITA</indexterm></indexterm>
<indexterm>DITA 1.3
<indexterm>Lightweight DITA</indexterm></indexterm>
<indexterm>converting lightweight formats to DITA</indexterm>
</keywords>
</metadata>
</prolog>
<body>
<note type="attention">Since
<xref keyref="lwdita"/> 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.</note>
<section>
<title>XDITA</title>
<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>The XDITA parser included in the <codeph>org.lwdita</codeph> plug-in provides preliminary support for XDITA
maps and XDITA topics.</p>
<p>To apply XDITA-specific processing to topics in an XDITA map or a full DITA 1.3 map, set the
<xmlatt>format</xmlatt> attribute on a <xmlelement>topicref</xmlelement> to <codeph>xdita</codeph>:</p>
<p>
<codeblock outputclass="language-xml normalize-space show-line-numbers show-whitespace">&lt;map>
&lt;topicref href="xdita-topic.xml" <b>format="xdita"</b>/>
&lt;/map></codeblock>
</p>
<note type="tip">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
<filepath>plugins/org.oasis-open.xdita.v0_2_2/samples</filepath>.</note>
</section>
<section>
<title>MDITA</title>
<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>Recent proposals for LwDITA include two profiles for authoring MDITA topics:</p>
<ul>
<li>The “<term>Core profile</term>” is based on
<xref keyref="gfm-spec"/> and includes elements that are common to many other Markdown implementations.</li>
<li>The “<term>Extended profile</term>” 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>The Markdown DITA parser included in the <codeph>org.lwdita</codeph> plug-in provides preliminary support for
these profiles and additional Markdown constructs as described in the syntax reference.</p>
<p>To apply LwDITA-specific processing to Markdown topics, set the <xmlatt>format</xmlatt> attribute to
<codeph>mdita</codeph>:</p>
<p>
<codeblock outputclass="language-xml normalize-space show-line-numbers show-whitespace">&lt;map>
&lt;topicref href="mdita-topic.md" <b>format="mdita"</b>/>
&lt;/map></codeblock>
</p>
<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>
<note>Setting the <xmlatt>format</xmlatt> attribute to <codeph>mdita</codeph> triggers stricter parsing than the
more lenient document parsing approach that is applied to <codeph>markdown</codeph> documents.</note>
<note type="attention">The MDITA map format is not yet supported. To include Markdown content in publications, use
an XDITA map or a DITA 1.3 map.</note>
</section>
<section>
<title>HDITA</title>
<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>The HDITA parser included in the <codeph>org.lwdita</codeph> plug-in provides preliminary support for these
constructs.</p>
<p>To apply LwDITA-specific processing to HTML topics, set the <xmlatt>format</xmlatt> attribute to
<codeph>hdita</codeph>:</p>
<p>
<codeblock outputclass="language-xml normalize-space show-line-numbers show-whitespace">&lt;map>
&lt;topicref href="hdita-topic.html" <b>format="hdita"</b>/>
&lt;/map></codeblock>
</p>
<note type="attention">The HDITA map format is not yet supported. To include HDITA content, use an XDITA map or a
DITA 1.3 map.</note>
</section>
<section>
<title>Converting lightweight formats to DITA XML</title>
<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>If you prefer to maintain this content in DITA in the future, you can generate DITA output by passing the
<parmname>--format</parmname>=<option>dita</option> option on the command line.</p>
<p>This converts all input files (both LwDITA formats and DITA XML) to
<xref keyref="dita2dita">Normalized DITA</xref>. 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>
</body>
</topic>

433
dita-ot-3.6/docsrc/topics/markdown-dita-syntax-reference.dita Normal file
View file

@ -0,0 +1,433 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<topic id="markdown-dita-syntax-reference">
<title>Markdown DITA syntax reference</title>
<titlealts>
<navtitle>Markdown DITA syntax</navtitle>
</titlealts>
<shortdesc>Markdown DITA uses
<xref keyref="commonmark"/> as the underlying markup language.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>Pandoc</indexterm>
<indexterm>UTF</indexterm>
<indexterm>DITA
<indexterm>specializations</indexterm></indexterm>
<indexterm>Markdown</indexterm>
<indexterm>CommonMark</indexterm>
</keywords>
</metadata>
</prolog>
<body>
<p>Markdown DITA files must be UTF-8 encoded.</p>
<section id="titles-and-document-structure">
<title>Titles and document structure</title>
<p>Each header level will generate a topic and associated title:</p>
<codeblock outputclass="language-markdown normalize-space show-line-numbers show-whitespace"># Topic title
## Nested topic title</codeblock>
<codeblock
outputclass="language-xml normalize-space show-line-numbers show-whitespace"
>&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;</codeblock>
<p>Pandoc
<xref
format="html#extension-header_attributes"
href="http://pandoc.org/MANUAL.html#extension-header_attributes"
scope="external"
>header_attributes</xref> can be used to define <codeph>id</codeph> or
<codeph>outputclass</codeph> attributes:</p>
<codeblock
outputclass="language-markdown normalize-space show-line-numbers show-whitespace"
># Topic title {#carrot .juice}</codeblock>
<codeblock
outputclass="language-xml normalize-space show-line-numbers show-whitespace"
>&lt;topic id="carrot" outputclass="juice"&gt;
&lt;title&gt;Topic title&lt;/title&gt;</codeblock>
<p>If topic ID is not defined using header_attributes, the ID is generated from title contents.</p>
<p>Pandoc
<xref
format="html#extension-pandoc_title_block"
href="http://pandoc.org/MANUAL.html#extension-pandoc_title_block"
scope="external"
>pandoc_title_block</xref>
extension can be used to group multiple level 1 headers under a common title:</p>
<codeblock outputclass="language-markdown normalize-space show-line-numbers show-whitespace">% Common title
# Topic title
# Second title</codeblock>
<codeblock
outputclass="language-xml normalize-space show-line-numbers show-whitespace"
>&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;</codeblock>
</section>
<section id="topic-content">
<title>Topic content</title>
<p>In LwDITA compatible documents (MDITA) the first paragraph is treated as a <codeph>shortdesc</codeph> element.
In generic Markdown documents all paragraphs appear inside the <codeph>body</codeph> element.</p></section>
<section id="specialization-types">
<title>Specialization types</title>
<p>The following class values in
<xref
format="html#extension-header_attributes"
href="http://pandoc.org/MANUAL.html#extension-header_attributes"
scope="external"
>header_attributes</xref> have a special meaning on level 1 headers:</p>
<ul>
<li>
<codeph>concept</codeph></li>
<li>
<codeph>task</codeph></li>
<li>
<codeph>reference</codeph></li>
</ul>
<p>They can be used to change the Markdown DITA topic type to one of the built-in structural specialization
types.</p>
<codeblock outputclass="language-markdown normalize-space show-line-numbers show-whitespace"># Task {.task}
Context
1. Command
Info.</codeblock>
<codeblock outputclass="language-xml normalize-space show-line-numbers show-whitespace">&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;</codeblock>
</section>
<section id="sections">
<title>Sections</title>
<p>The following class values in
<xref
format="html#extension-header_attributes"
href="http://pandoc.org/MANUAL.html#extension-header_attributes"
scope="external"
>header_attributes</xref> have a special meaning on header levels other than 1:</p>
<ul>
<li>
<codeph>section</codeph></li>
<li>
<codeph>example</codeph></li>
</ul>
<p>They are used to generate
<xref
format="html"
href="http://docs.oasis-open.org/dita/v1.2/os/spec/langref/section.html"
scope="external"
><codeph>section</codeph></xref> and
<xref
format="html"
href="http://docs.oasis-open.org/dita/v1.2/os/spec/langref/example.html"
scope="external"
><codeph>example</codeph></xref> elements:</p>
<codeblock outputclass="language-markdown normalize-space show-line-numbers show-whitespace"># Topic title
## Section title {.section}
## Example title {.example}</codeblock>
<codeblock
outputclass="language-xml normalize-space show-line-numbers show-whitespace"
>&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;</codeblock>
</section>
<section id="hard-line-breaks">
<title>Hard line breaks</title>
<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
<codeph>&lt;br&gt;</codeph> element for line break, hard line breaks are converted into
<xmlpi>linebreak</xmlpi> processing instructions.</p>
<codeblock outputclass="language-markdown normalize-space show-line-numbers show-whitespace">foo··
baz</codeblock>
<codeblock
outputclass="language-xml normalize-space show-line-numbers show-whitespace"
>&lt;p>foo&lt;?linebreak?>baz&lt;/p></codeblock>
</section>
<section id="links">
<title>Links</title>
<p>The format of local link targets is detected based on file extension. The following extensions are treated as
DITA files:</p>
<table outputclass="table-hover" frame="none" colsep="0" rowsep="1">
<tgroup cols="2">
<colspec/>
<colspec/>
<thead>
<row>
<entry>extension</entry>
<entry>format</entry>
</row>
</thead>
<tbody>
<row>
<entry><codeph>.dita</codeph></entry>
<entry><codeph>dita</codeph></entry>
</row>
<row>
<entry><codeph>.xml</codeph></entry>
<entry><codeph>dita</codeph></entry>
</row>
<row>
<entry><codeph>.md</codeph></entry>
<entry><codeph>markdown</codeph></entry>
</row>
<row>
<entry><codeph>.markdown</codeph></entry>
<entry><codeph>markdown</codeph></entry>
</row>
</tbody>
</tgroup>
</table>
<p>All other link targets use <codeph>format</codeph> from file extension and are treated as non-DITA files.
Absolute links targets are treated as external scope links:</p>
<codeblock outputclass="language-markdown normalize-space show-line-numbers show-whitespace">[Markdown](test.md)
[DITA](test.dita)
[HTML](test.html)
[External](http://www.example.com/test.html)</codeblock>
<codeblock
outputclass="language-xml normalize-space show-line-numbers show-whitespace"
>&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;</codeblock>
</section>
<section id="images">
<title>Images</title>
<indexterm>images
<indexterm>Markdown</indexterm></indexterm>
<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>
<codeblock
outputclass="language-markdown normalize-space show-line-numbers show-whitespace"
>An inline ![Alt](test.jpg).
![Alt](test.jpg)
![Alt](test.jpg "Title")</codeblock>
<codeblock
outputclass="language-xml normalize-space show-line-numbers show-whitespace"
>&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;</codeblock>
</section>
<section id="key-references">
<title>Key references</title>
<p>Key reference can be used with
<xref format="html" href="http://spec.commonmark.org/0.18/#shortcut-reference-link" scope="external">shortcut
reference links</xref>:</p>
<codeblock outputclass="language-markdown normalize-space show-line-numbers show-whitespace">[key]
![image-key]</codeblock>
<codeblock outputclass="language-xml normalize-space show-line-numbers show-whitespace">&lt;xref keyref="key"/&gt;
&lt;image keyref="image-key"/&gt;</codeblock>
</section>
<section id="inline">
<title>Inline</title>
<p>The following inline elements are supported:</p>
<codeblock outputclass="language-markdown normalize-space show-line-numbers show-whitespace">**bold**
*italic*
`code`
~~strikethrough~~</codeblock>
<codeblock outputclass="language-xml normalize-space show-line-numbers show-whitespace">&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;</codeblock>
</section>
<section id="lists">
<title>Lists</title>
<p>Unordered can be marked up with either hyphen or asterisk:</p>
<codeblock outputclass="language-markdown normalize-space show-line-numbers show-whitespace">* one
* two
- three
- four</codeblock>
<codeblock outputclass="language-xml normalize-space show-line-numbers show-whitespace">&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;</codeblock>
<p>Ordered can be marked up with either number or number sign, followed by a period:</p>
<codeblock outputclass="language-markdown normalize-space show-line-numbers show-whitespace">1. one
2. two
#. three
#. four</codeblock>
<codeblock outputclass="language-xml normalize-space show-line-numbers show-whitespace">&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;</codeblock>
<p>Definition lists use the
<xref format="html" href="http://michelf.com/projects/php-markdown/extra/#def-list" scope="external">PHP
Markdown Extra</xref> format:</p>
<codeblock outputclass="language-markdown normalize-space show-line-numbers show-whitespace">Term
: Definition.</codeblock>
<codeblock outputclass="language-xml normalize-space show-line-numbers show-whitespace">&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;</codeblock>
<p>Each definition entry must have only one term and contain only inline content.</p></section>
<section id="tables">
<title>Tables</title>
<indexterm>tables
<indexterm>Markdown</indexterm></indexterm>
<p>Tables use
<xref format="html" href="http://fletcherpenney.net/multimarkdown/" scope="external">MultiMarkdown</xref> table
extension format:</p>
<codeblock
outputclass="normalize-space show-line-numbers show-whitespace"
>| First Header | Second Header | Third Header |
| ------------ | :-----------: | -----------: |
| Content | *Long Cell* ||
| Content | **Cell** | Cell |</codeblock>
<codeblock outputclass="language-xml normalize-space show-line-numbers show-whitespace">&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;</codeblock>
<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 id="metadata">
<title>Metadata</title>
<indexterm>metadata
<indexterm>Lightweight DITA</indexterm></indexterm>
<indexterm>metadata
<indexterm>Markdown</indexterm></indexterm>
<indexterm>Pandoc</indexterm>
<p>
<xref format="html" href="http://www.yaml.org/" scope="external">YAML</xref> metadata block as defined in Pandoc
<xref
format="html#extension-yaml_metadata_block"
href="http://pandoc.org/MANUAL.html#extension-yaml_metadata_block"
scope="external"
>pandoc_metadata_block</xref> can be used to specify different metadata elements. The supported elements
are:</p>
<ul>
<li>
<codeph>author</codeph></li>
<li>
<codeph>source</codeph></li>
<li>
<codeph>publisher</codeph></li>
<li>
<codeph>permissions</codeph></li>
<li>
<codeph>audience</codeph></li>
<li>
<codeph>category</codeph></li>
<li>
<codeph>keyword</codeph></li>
<li>
<codeph>resourceid</codeph></li>
</ul>
<p>Unrecognized keys are output using <codeph>data</codeph> element.</p>
<codeblock outputclass="language-markdown normalize-space show-line-numbers show-whitespace">---
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</codeblock>
<codeblock
outputclass="language-xml normalize-space show-line-numbers show-whitespace"
>&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;</codeblock>
</section>
</body>
</topic>

71
dita-ot-3.6/docsrc/topics/markdown-input.dita Normal file
View file

@ -0,0 +1,71 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<topic id="markdown-input">
<title>Markdown content</title>
<shortdesc>
<xref keyref="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.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm><xmlatt>format</xmlatt></indexterm>
<indexterm>authoring formats
<indexterm>Markdown</indexterm></indexterm>
<indexterm>Markdown</indexterm>
<indexterm>CommonMark</indexterm>
<indexterm>converting lightweight formats to DITA</indexterm>
</keywords>
</metadata>
</prolog>
<body>
<p>In the words of its creators:</p>
<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.”</lq>
<p>DITA Open Toolkit now allows you to use Markdown files directly in topic references and export DITA content as
Markdown.</p>
<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>
<title>Adding Markdown topics</title>
<p>To add a Markdown topic to a DITA publication, create a topic reference in your map and set the
<xmlatt>format</xmlatt> attribute to <codeph>markdown</codeph> so the toolkit will recognize the source file
as Markdown and convert it to DITA:</p>
<p><codeblock
outputclass="language-xml normalize-space show-line-numbers show-whitespace"
>&lt;?xml version="1.0" encoding="utf-8"?>
&lt;!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
&lt;map>
&lt;topicref href="markdown-dita-topic.md" <b>format="markdown"</b>/>
&lt;/map></codeblock></p>
<p>The <codeph>markdown</codeph> format uses a relatively lenient document parsing approach to support a wide
range of content and Markdown syntax constructs.</p>
<note>The Markdown support is based on
<xref keyref="commonmark"/>, a strongly defined, highly compatible specification of Markdown.</note>
<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>
<note type="tip">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.</note>
</section>
<section>
<title>Converting Markdown to DITA</title>
<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>If you prefer to maintain this content in DITA in the future, you can generate DITA output by passing the
<parmname>--format</parmname>=<option>dita</option> option on the command line.</p>
<p>This converts all input files (both DITA XML and Markdown) to
<xref keyref="dita2dita">Normalized DITA</xref>. 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>
</body>
</topic>

123
dita-ot-3.6/docsrc/topics/migrating-ant-to-dita.dita Normal file
View file

@ -0,0 +1,123 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA General Task//EN" "generalTask.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<task id="migrating-ant-to-dita">
<title>Migrating Ant builds to use the <cmdname>dita</cmdname> command</title>
<titlealts>
<navtitle>Migrating Ant builds</navtitle>
</titlealts>
<shortdesc>Although DITA Open Toolkit still supports Ant builds, switching to the <cmdname>dita</cmdname> command
offers a simpler command interface, sets all required environment variables and allows you to run DITA-OT without
setting up anything beforehand.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>Ant
<indexterm><xmlelement>exec</xmlelement></indexterm></indexterm>
<indexterm>Ant
<indexterm><xmlelement>dita-cmd</xmlelement></indexterm>
<indexterm><cmdname>dita</cmdname> command, benefits of</indexterm></indexterm>
<indexterm>dita-cmd</indexterm>
<indexterm><cmdname>dita</cmdname> command
<indexterm>migrating Ant scripts</indexterm></indexterm>
<indexterm>classpath
<indexterm><cmdname>dita</cmdname> command</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<taskbody>
<context>
<p>Building output with the <cmdname>dita</cmdname> command is often easier than using Ant. In particular, you can
use <filepath>.properties</filepath> files to specify sets of DITA-OT parameters for each build.</p>
<p>You can include the <cmdname>dita</cmdname> command in shell scripts to perform multiple builds.</p>
<note type="tip">Add the absolute path for the <filepath>bin</filepath> folder of the DITA-OT installation
directory to the
<xref keyref="PATH"/> to run the <cmdname>dita</cmdname> command from any location on the file system without
typing the path.</note>
</context>
<steps>
<step>
<cmd>In your Ant build file, identify the properties set in each build target.</cmd>
<info>
<note>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.</note>
</info>
</step>
<step>
<cmd>Create a <filepath>.properties</filepath> file for each build and specify the needed build parameters, one
per line, in the format <codeph>name = value</codeph>.</cmd>
</step>
<step>
<cmd>Use the <cmdname>dita</cmdname> command to perform each build, referencing your
<filepath>.properties</filepath> with the <parmname>--propertyfile</parmname>=<varname>file</varname>
option.</cmd>
</step>
</steps>
<example>
<title>Example: Ant build</title>
<p>Prior to DITA-OT 2.0, an Ant build like this was typically used to define the properties for each target.</p>
<p>Sample build file: <filepath id="samples-dir"><varname>dita-ot-dir</varname>/docsrc/samples</filepath><filepath
>/ant_sample/build-chm-pdf.xml</filepath>
<codeblock outputclass="language-xml normalize-space show-line-numbers show-whitespace"><coderef
href="../samples/ant_sample/build-chm-pdf.xml"
/></codeblock></p></example>
<example>
<title>Example: <filepath>.properties</filepath> files with <cmdname>dita</cmdname> command</title>
<p>The following <filepath>.properties</filepath> files and <cmdname>dita</cmdname> commands are equivalent to the
example Ant build.</p>
<p>Sample <filepath>.properties</filepath> file: <filepath conkeyref="conref-task/samples-dir"/><filepath
>/properties/chm.properties</filepath></p>
<p>
<codeblock outputclass="language-properties normalize-space show-line-numbers show-whitespace"><coderef
href="../samples/properties/chm.properties"
/></codeblock></p>
<p>Sample <filepath>.properties</filepath> file: <filepath conkeyref="conref-task/samples-dir"/><filepath
>/properties/pdf.properties</filepath></p>
<p>
<codeblock outputclass="language-properties normalize-space show-line-numbers show-whitespace"><coderef
href="../samples/properties/pdf.properties"
/></codeblock></p>
<p>Run from <filepath conkeyref="conref-task/samples-dir"/>:</p>
<codeblock><cmdname>dita</cmdname> <parmname>--input</parmname>=<filepath>sequence.ditamap</filepath> <parmname
>--format</parmname>=<option>htmlhelp</option> \
<parmname>--propertyfile</parmname>=<filepath>properties/chm.properties</filepath>
<cmdname>dita</cmdname> <parmname>--input</parmname>=<filepath>taskbook.ditamap</filepath> <parmname
>--format</parmname>=<option>pdf</option> \
<parmname>--propertyfile</parmname>=<filepath>properties/pdf.properties</filepath></codeblock>
</example>
<example>
<title>Example: Call the <cmdname>dita</cmdname> command from an Ant build</title>
<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 <cmdname>dita</cmdname> command with <filepath>.properties</filepath>
files to define the parameters for each build. This can be accomplished with Ant’s <xmlelement>exec</xmlelement>
task.</p>
<p>This example uses a <xmlelement>dita-cmd</xmlelement> Ant macro defined in the <filepath
conkeyref="conref-task/samples-dir"
/><filepath>/ant_sample/dita-cmd.xml</filepath> file:</p>
<p>
<codeblock outputclass="language-xml normalize-space show-line-numbers show-whitespace"><coderef
href="../samples/ant_sample/dita-cmd.xml#line-range(10,30)"
/></codeblock></p>
<p>You can use this macro in your Ant build to call the <cmdname>dita</cmdname> command and pass the
<parmname>input</parmname>, <parmname>format</parmname> and <parmname>propertyfile</parmname> parameters as
follows:
<codeblock
outputclass="language-xml"
>&lt;dita-cmd input="sample.ditamap" format="pdf" propertyfile="sample.properties"/></codeblock>
</p>
<p>This approach allows you to use Ant builds to perform additional tasks at build time while allowing the
<cmdname>dita</cmdname> command to set the classpath and ensure that all necessary JAR libraries are
available.</p>
<note>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 <filepath>.properties</filepath> files for
each build.</note>
<p>Sample build file: <filepath conkeyref="conref-task/samples-dir"/><filepath
>/ant_sample/build-chm-pdf-hybrid.xml</filepath></p>
<p>
<codeblock outputclass="language-xml normalize-space show-line-numbers show-whitespace"><coderef
href="../samples/ant_sample/build-chm-pdf-hybrid.xml"
/></codeblock>
</p>
</example>
</taskbody>
</task>

197
dita-ot-3.6/docsrc/topics/migrating-to-1.5.4.dita Normal file
View file

@ -0,0 +1,197 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<reference id="ID" rev="1.5.4">
<title>Migrating to release 1.5.4</title>
<titlealts>
<navtitle>To 1.5.4</navtitle>
</titlealts>
<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.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>deprecated features
<indexterm><codeph>print_transtypes</codeph></indexterm></indexterm>
<indexterm>deprecated features
<indexterm><codeph>page-margin-left</codeph></indexterm></indexterm>
<indexterm>deprecated features
<indexterm><codeph>page-margin-right</codeph></indexterm></indexterm>
<indexterm>languages
<indexterm>supported</indexterm></indexterm>
<indexterm>Finnish</indexterm>
<indexterm>Hebrew</indexterm>
<indexterm>Indonesian</indexterm>
<indexterm>Kazakh</indexterm>
<indexterm>Malay</indexterm>
<indexterm>Romanian</indexterm>
<indexterm>Russian</indexterm>
<indexterm>Swedish</indexterm>
<indexterm>I18N
<indexterm><parmname>org.dita.pdf2.i18n.enabled</parmname></indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<refbody>
<section id="section_vc5_gld_g2">
<title>Configuration properties file changes</title>
<p>In previous versions, the <filepath>lib/configuration.properties</filepath> file was generated by the
integration process. Integration has been changed to generate
<filepath>lib/org.dita.dost.platform/plugin.properties</filepath> and the role of the old
<filepath>lib/configuration.properties</filepath> has been changed to contain defaults and configuration
options, such as default language.</p>
<p>The <codeph>dita.plugin.org.dita.*.dir</codeph> properties have been changed to point to the DITA-OT base
directory.</p>
<p>To allow access to configuration files, the <filepath>lib</filepath> directory needs to be added to the Java
classpath.</p>
</section>
<section>
<title>New plug-in extension points </title>
<p>New plug-in extension points have been added allow configuring DITA-OT behavior based on file extensions.</p>
<table outputclass="table-hover" frame="none" colsep="0" rowsep="1">
<tgroup cols="3">
<colspec colwidth="1*"/>
<colspec colwidth="1*"/>
<colspec colwidth="1*"/>
<thead>
<row>
<entry>Extension point</entry>
<entry>Description</entry>
<entry>Default values</entry>
</row>
</thead>
<tbody>
<row>
<entry><parmname>dita.topic.extension</parmname></entry>
<entry>DITA topic</entry>
<entry><filepath>.dita</filepath>, <filepath>.xml</filepath></entry>
</row>
<row>
<entry><parmname>dita.map.extensions</parmname></entry>
<entry>DITA map</entry>
<entry><filepath>.ditamap</filepath></entry>
</row>
<row>
<entry><parmname>dita.html.extensions</parmname></entry>
<entry>HTML file</entry>
<entry><filepath>.html</filepath>, <filepath>.htm</filepath></entry>
</row>
<row>
<entry><parmname>dita.resource.extensions</parmname></entry>
<entry>Resource file</entry>
<entry><filepath>.pdf</filepath>, <filepath>.swf</filepath></entry>
</row>
</tbody>
</tgroup>
</table>
<p>Both HTML and resource file extensions are used to determine if a file in source is copied to output.</p>
<p>A new plug-in extension point has been added to declare transformation types as print types.</p>
<table outputclass="table-hover" frame="none" colsep="0" rowsep="1">
<tgroup cols="2">
<colspec colwidth="1*"/>
<colspec colwidth="1*"/>
<thead>
<row>
<entry>Extension point</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><parmname>dita.transtype.print</parmname></entry>
<entry>Declare transformation type as a print type.</entry>
</row>
</tbody>
</tgroup>
</table>
<p>The <codeph>print_transtypes</codeph> property in <filepath>integrator.properties</filepath> has been
deprecated in favor of <parmname>dita.transtype.print</parmname>.</p>
</section>
<section>
<title>Plugin URI scheme</title>
<p>Support for the <keyword>plugin</keyword> 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>
<codeblock
outputclass="language-xml"
xml:space="preserve"
>&lt;xsl:import href="plugin:org.dita.pdf2:xsl/fo/topic2fo_1.0.xsl"/&gt;</codeblock>
</section>
<section>
<title>XHTML</title>
<p>Support for the following languages has been added:</p>
<ul>
<li>Indonesian</li>
<li>Kazakh</li>
<li>Malay</li>
</ul>
</section>
<section>
<title>PDF</title>
<p>Support for mirrored page layout was added. The default is the unmirrored layout. The following XSLT
configuration variables have been deprecated:</p>
<ul id="ul_hkv_oyj_bd">
<li><codeph>page-margin-left</codeph></li>
<li><codeph>page-margin-right</codeph></li>
</ul>
<p>The following variables should be used instead to control page margins:</p>
<ul id="ul_yda_wyj_bd">
<li><codeph>page-margin-outside</codeph></li>
<li><codeph>page-margin-inside</codeph></li>
</ul>
<p>The <parmname>args.bookmap-order</parmname> 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>A new extension point has been added to add mappings to the PDF configuration catalog file.</p>
<table outputclass="table-hover" frame="none" colsep="0" rowsep="1">
<tgroup cols="2">
<colspec colwidth="1*"/>
<colspec colwidth="1*"/>
<thead>
<row>
<entry>Extension point</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><parmname>org.dita.pdf2.catalog.relative</parmname></entry>
<entry>Configuration catalog includes.</entry>
</row>
</tbody>
</tgroup>
</table>
<p>Support for the following languages has been added:</p>
<ul>
<li>Finnish</li>
<li>Hebrew</li>
<li>Romanian</li>
<li>Russian</li>
<li>Swedish</li>
</ul>
<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 <parmname>org.dita.pdf2.use-out-temp</parmname> to
<option>true</option> in configuration properties; support for the legacy processing model may be removed in
future releases.</p>
<p>Support for FrameMaker index syntax has been disabled by default. To enable FrameMaker index syntax, set
<parmname>org.dita.pdf2.index.frame-markup</parmname> to <option>true</option> in configuration
properties.</p>
<p>A configuration option has been added to disable internationalization (I18N) font processing and use
stylesheet-defined fonts. To disable I18N font processing, set <parmname>org.dita.pdf2.i18n.enabled</parmname>
to <codeph>false</codeph> in configuration properties.</p>
<p>The XSLT parameters <parmname>customizationDir</parmname> and <parmname>fileProfilePrefix</parmname> have been
removed in favor of the <parmname>customizationDir.url</parmname> parameter.</p>
<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>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>
</refbody>
</reference>

208
dita-ot-3.6/docsrc/topics/migrating-to-1.6.dita Normal file
View file

@ -0,0 +1,208 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<reference id="ID" rev="1.6">
<title>Migrating to release 1.6</title>
<titlealts>
<navtitle>To 1.6</navtitle>
</titlealts>
<shortdesc>In DITA-OT 1.6, various <filepath>demo</filepath> 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 <filepath>layout-masters.xml</filepath> configuration.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>deprecated features
<indexterm><filepath>demo</filepath> folder</indexterm></indexterm>
<indexterm>deprecated features
<indexterm><codeph>workdir</codeph> processing instruction</indexterm></indexterm>
<indexterm>deprecated features
<indexterm><codeph>workdir</codeph> processing instruction</indexterm></indexterm>
<indexterm>deprecated features
<indexterm>topic pull templates, list of</indexterm></indexterm>
<indexterm>deprecated features
<indexterm>"bkinfo" demo plug-in</indexterm></indexterm>
<indexterm>deprecated features
<indexterm><filepath>layout-masters.xml</filepath></indexterm></indexterm>
<indexterm>deprecated features
<indexterm>PDF2 templates, list of</indexterm></indexterm>
<indexterm>deprecated features
<indexterm>XHTML templates, list of</indexterm></indexterm>
<indexterm>deprecated features
<indexterm>ODT templates, list of</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<refbody>
<section>
<p>Support for the old DITAVAL format (used before OASIS added DITAVAL to the standard in 2007) has been
removed.</p>
<p>The <filepath>demo</filepath> folder has been deprecated and the following plug-ins have been moved to the
<filepath>plugins</filepath> folder:</p>
<table outputclass="table-hover" frame="none" colsep="0" rowsep="1">
<tgroup cols="2">
<colspec colwidth="1*"/>
<colspec colwidth="1*"/>
<thead>
<row>
<entry>old path</entry>
<entry>new path</entry>
</row>
</thead>
<tbody>
<row>
<entry><filepath>demo/dita11</filepath></entry>
<entry><filepath>plugins/org.dita.specialization.dita11</filepath></entry>
</row>
<row>
<entry><filepath>demo/dita132</filepath></entry>
<entry><filepath>plugins/org.dita.specialization.dita132</filepath></entry>
</row>
<row>
<entry><filepath>demo/eclipsemap</filepath></entry>
<entry><filepath>plugins/org.dita.specialization.eclipsemap</filepath></entry>
</row>
<row>
<entry><filepath>demo/fo</filepath></entry>
<entry><filepath>plugins/org.dita.pdf2</filepath></entry>
</row>
<row>
<entry><filepath>demo/tocjs</filepath></entry>
<entry><filepath>plugins/com.sophos.tocjs</filepath></entry>
</row>
<!-- These plugins are pulled from ext-plugins during build -->
<row>
<entry><filepath>demo/h2d</filepath></entry>
<entry><filepath>plugins/h2d</filepath></entry>
</row>
<row>
<entry><filepath>demo/legacypdf</filepath></entry>
<entry><filepath>plugins/legacypdf</filepath></entry>
</row>
</tbody>
</tgroup>
</table>
<p>The remaining plug-ins in the demo folder have been moved to a separate repository at
<xref
href="https://github.com/dita-ot/ext-plugins"
scope="external"
format="html"
>github.com/dita-ot/ext-plugins</xref>.</p>
</section>
<section>
<p>The deprecated property <codeph>dita.input.valfile</codeph> should be replaced with the new argument property
<codeph>args.filter</codeph>.</p>
<p>The <codeph>dita-preprocess</codeph> target has been removed and dependencies should be replaced with a target
sequence <codeph>build-init, preprocess</codeph>.</p>
<p>Support for the <codeph>args.message.file</codeph> argument has been removed as message configuration has
become static configuration.</p>
<p>The <codeph>workdir</codeph> processing instruction has been deprecated in favor of
<codeph>workdir-uri</codeph>. The only difference between the two processing instructions is that
<codeph>workdir-uri</codeph> contains a URI instead of a system path.</p>
</section>
<section>
<title>Preprocessing</title>
<p>The following deprecated templates and modes have been removed in topic pull stylesheets:</p>
<ul>
<li>inherit</li>
<li>get-stuff</li>
<li>verify-type-attribute</li>
<li>classval</li>
<li>getshortdesc</li>
<li>getlinktext</li>
<li>blocktext</li>
<li>figtext</li>
<li>tabletext</li>
<li>litext</li>
<li>fntext</li>
<li>dlentrytext</li>
<li>firstclass</li>
<li>invalid-list-item</li>
<li>xref</li>
</ul>
</section>
<section>
<title>PDF2</title>
<p>The following deprecated items are no longer supported in the PDF transform:</p>
<ul>
<li>Support for the beta version of DITA, available from IBM before the OASIS standard was created in 2005.</li>
<li>Support for the "bkinfo" demo plug-in, used to support book metadata before OASIS created the BookMap format
in 2007.</li>
<li>Support for <filepath>layout-masters.xml</filepath> configuration. Plug-ins should use the
<codeph>createDefaultLayoutMasters</codeph> template instead.</li>
</ul>
<p>The following extension-points have been added:</p>
<ul>
<li><codeph>dita.conductor.pdf2.param</codeph> to add XSLT parameters to XSL FO transformation.</li>
</ul>
<p>Custom PDF2 shell stylesheets need to be revised to not include separate IBM and OASIS DITA stylesheets. The
<filepath><varname>*</varname>_1.0.xsl</filepath> stylesheets have been removed and their imports must be
removed from shell stylesheets.</p>
<p>The following template modes have been deprecated:</p>
<ul>
<li>toc-prefix-text</li>
<li>toc-topic-text</li>
</ul>
<p>The following named templates have been removed:</p>
<ul>
<li>processTopic</li>
<li>createMiniToc</li>
<li>processTopicTitle</li>
<li>createTopicAttrsName</li>
<li>processConcept</li>
<li>processReference</li>
<li>getTitle</li>
<li>placeNoteContent</li>
<li>placeImage</li>
<li>processUnknowType</li>
<li>insertReferenceTitle</li>
<li>buildRelationships</li>
<li>processTask</li>
</ul>
<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>
<title>XHTML</title>
<p>The following named templates have been deprecated:</p>
<ul>
<li>make-index-ref</li>
</ul>
<p>The following deprecated templates have been removed:</p>
<ul>
<li>revblock-deprecated</li>
<li>revstyle-deprecated</li>
<li>start-revision-flag-deprecated</li>
<li>end-revision-flag-deprecated</li>
<li>concept-links</li>
<li>task-links</li>
<li>reference-links</li>
<li>relinfo-links</li>
<li>sort-links-by-role</li>
<li>create-links</li>
<li>add-linking-attributes</li>
<li>add-link-target-attribute</li>
<li>add-user-link-attributes</li>
</ul>
<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>
<title>ODT</title>
<p>The following deprecated templates have been removed:</p>
<ul>
<li>revblock-deprecated</li>
<li>revstyle-deprecated</li>
<li>start-revision-flag-deprecated</li>
<li>end-revision-flag-deprecated</li>
</ul>
<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>
</refbody>
</reference>

110
dita-ot-3.6/docsrc/topics/migrating-to-1.7.dita Normal file
View file

@ -0,0 +1,110 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<reference id="ID" rev="1.7">
<title>Migrating to release 1.7</title>
<titlealts>
<navtitle>To 1.7</navtitle>
</titlealts>
<shortdesc>In DITA-OT 1.7, a new preprocessing step implements flagging for HTML-based output formats. PDF processing
was corrected with regard to <codeph>shortdesc</codeph> 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. </shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>deprecated features
<indexterm><codeph>dita.input</codeph></indexterm></indexterm>
<indexterm>deprecated features
<indexterm><codeph>dita.input.dirname</codeph></indexterm></indexterm>
<indexterm>deprecated features
<indexterm><codeph>dita.extname</codeph></indexterm></indexterm>
<indexterm>deprecated features
<indexterm>XHTML, flagging-related templates</indexterm></indexterm>
<indexterm>deprecated features
<indexterm><codeph>page-margin-left</codeph></indexterm></indexterm>
<indexterm>deprecated features
<indexterm><codeph>page-margin-right</codeph></indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<refbody>
<section>
<p>A new job status file <filepath>.job.xml</filepath> has been introduced and replaces
<filepath>dita.list</filepath> and <filepath>dita.xml.properties</filepath> as the normative source for job
status. If you have custom processing which modifies the job properties, you should change your code to modify
<filepath>.job.xml</filepath> instead.</p>
<p>Support for the following deprecated properties has been removed:</p>
<ul>
<li><codeph>dita.input</codeph></li>
<li><codeph>dita.input.dirname</codeph></li>
<li><codeph>dita.extname</codeph></li>
</ul>
<p>Stylesheets for the following transformation types have moved to plug-in specific folders:</p>
<ul>
<li><option>docbook</option></li>
<li><option>eclipsecontent</option></li>
<li><option>troff</option></li>
<li><option>wordrtf</option></li>
</ul>
<p>If custom plug-ins have hard coded paths to these stylesheets, update references to use either
<codeph>plugin</codeph> URIs in <codeph>xsl:import</codeph> instructions or use <codeph>dita.plugin.*</codeph>
Ant properties.</p>
<p>The integration process has been changed to use strict mode by default. For old plug-ins which are not valid,
<keyword>lax</keyword> processing mode can still be used.</p>
<p>Plug-ins that use the <codeph>MessageUtils</codeph> Java class must use <codeph>getInstance</codeph> method to
access the <codeph>MessageUtils</codeph> instance, as <codeph>getMessage</codeph> methods have been changed to
instance methods.</p>
</section>
<section>
<title>Preprocessing</title>
<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 <codeph>preprocess</codeph>
task.</p>
</section>
<section>
<title>HTML</title>
<p>Core TOC generation has been moved to a separate XSLT stylesheet
<filepath>xsl/map2htmtoc/map2htmlImpl.xsl</filepath> and the new templates use the mode <codeph>toc</codeph>.
Plug-ins which override HTML TOC processing should change the map processing templates to <codeph>toc</codeph>
mode.</p>
</section>
<section>
<title>HTML and extended transformation types</title>
<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>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
<xref keyref="flagging-migration"/> for details.</p>
<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
<xref keyref="preprocess-flagging"/> for details on how to add flagging support.</p>
</section>
<section>
<title>PDF</title>
<p>The following deprecated XSLT variables have been removed:</p>
<ul>
<li><codeph>page-margin-left</codeph></li>
<li><codeph>page-margin-right</codeph></li>
</ul>
<p>XSLT stylesheets have been split to separate specialization topic code and new <codeph>xsl:import</codeph>
instructions have been added to <filepath>topic2fo.xsl</filepath>. Plug-ins which define their own shell
stylesheet should be revised to import all the required stylesheet modules.</p>
<p>PDF processing used to replace topic <codeph>shortdesc</codeph> with map <codeph>shortdesc</codeph>, but this
behavior was incorrect and was removed to comply with the DITA specification.</p>
<p>A new <codeph>#note-separator</codeph> variable string was added to facilitate customization.</p>
</section>
</refbody>
</reference>

139
dita-ot-3.6/docsrc/topics/migrating-to-1.8.dita Normal file
View file

@ -0,0 +1,139 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<reference id="ID" rev="1.8">
<title>Migrating to release 1.8</title>
<titlealts>
<navtitle>To 1.8</navtitle>
</titlealts>
<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.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>deprecated features
<indexterm><codeph>dita.script.dir</codeph></indexterm></indexterm>
<indexterm>deprecated features
<indexterm><codeph>dita.resource.dir</codeph></indexterm></indexterm>
<indexterm>deprecated features
<indexterm><codeph>dita.empty</codeph></indexterm></indexterm>
<indexterm>deprecated features
<indexterm><codeph>args.message.file</codeph></indexterm></indexterm>
<indexterm>deprecated features
<indexterm><codeph>ImgUtils</codeph></indexterm></indexterm>
<indexterm>deprecated features
<indexterm><filepath>artwork-preprocessor.xsl</filepath></indexterm></indexterm>
<indexterm>deprecated features
<indexterm><filepath>otdita2fo_frontend.xsl</filepath></indexterm></indexterm>
<indexterm>deprecated features
<indexterm><codeph>insertVariable.old</codeph></indexterm></indexterm>
<indexterm>deprecated features
<indexterm>XSLT mode, <codeph>layout-masters-processing</codeph></indexterm></indexterm>
<indexterm>deprecated features
<indexterm>XSLT mode, <codeph>toc-prefix-text</codeph></indexterm></indexterm>
<indexterm>deprecated features
<indexterm>XSLT mode, <codeph>toc-topic-text</codeph></indexterm></indexterm>
<indexterm>deprecated features
<indexterm><codeph>args.fo.include.rellinks</codeph></indexterm></indexterm>
<indexterm>deprecated features
<indexterm>Legacy PDF</indexterm></indexterm>
<indexterm>deprecated features
<indexterm><codeph>args.odt.include.rellinks</codeph></indexterm></indexterm>
<indexterm>deprecated features
<indexterm><codeph>disableRelatedLinks</codeph></indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<refbody>
<section>
<p>Stylesheets for the following transformation types have moved to plug-in specific folders:</p>
<ul>
<li><option>eclipsehelp</option></li>
<li><option>htmlhelp</option></li>
<li><option>javahelp</option></li>
<li><option>odt</option></li>
<li><option>xhtml</option></li>
</ul>
</section>
<section>
<title>Preprocessing</title>
<p>The following deprecated Ant properties have been removed:</p>
<ul>
<li><codeph>dita.script.dir</codeph>, use <codeph>${dita.plugin.<varname>id</varname>.dir}</codeph> instead</li>
<li><codeph>dita.resource.dir</codeph>, use <codeph>${dita.plugin.org.dita.base.dir}/resource</codeph>
instead</li>
<li><codeph>dita.empty</codeph></li>
<li><codeph>args.message.file</codeph></li>
</ul>
</section>
<section>
<title>XHTML</title>
<p>XSLT Java extension <codeph>ImgUtils</codeph> has been removed from stylesheets and been replaced with
preprocessing module <codeph>ImageMetadataModule</codeph>. The old <codeph>ImgUtils</codeph> Java classes are
still included in the build.</p>
</section>
<section>
<title>PDF</title>
<indexterm>args.rellinks</indexterm>
<indexterm>PDF
<indexterm>related links</indexterm>
<indexterm>args.rellinks</indexterm></indexterm>
<p>The following deprecated XSLT stylesheets have been removed:</p>
<ul>
<li><filepath>artwork-preprocessor.xsl</filepath></li>
<li><filepath>otdita2fo_frontend.xsl</filepath></li>
</ul>
<p>The following deprecated XSLT templates have been removed:</p>
<ul>
<li><codeph>insertVariable.old</codeph></li>
</ul>
<p>The following deprecated XSLT modes have been removed:</p>
<ul>
<li><codeph>layout-masters-processing</codeph></li>
<li><codeph>toc-prefix-text</codeph>, use <codeph>tocPrefix</codeph> mode instead</li>
<li><codeph>toc-topic-text</codeph>, use <codeph>tocText</codeph> mode instead</li>
</ul>
<p>Link generation has been simplified by removing deprecated arguments in favor of
<codeph>args.rellinks</codeph>. The following deprecated Ant properties have been removed:</p>
<ul>
<li><codeph>args.fo.include.rellinks</codeph></li>
</ul>
<p>The following XSLT parameters have been removed:</p>
<ul>
<li><codeph>antArgsIncludeRelatedLinks</codeph></li>
<li><codeph>disableRelatedLinks</codeph></li>
</ul>
<p>A call to a named template <codeph>pullPrologIndexTerms.end-range</codeph> has been added to
<codeph>processTopic*</codeph> templates to handle topic wide index ranges.</p>
</section>
<section>
<title>Legacy PDF</title>
<p>The following deprecated XSLT stylesheets have been removed:</p>
<ul>
<li><filepath>dita2fo-shell_template.xsl</filepath></li>
<li><filepath>topic2fo-shell.xsl</filepath></li>
</ul>
</section>
<section>
<title>ODT</title>
<p>Link generation has been simplified by removing deprecated arguments in favor of
<codeph>args.rellinks</codeph>. The following deprecated Ant properties have been removed:</p>
<ul>
<li><codeph>args.odt.include.rellinks</codeph></li>
</ul>
<p>The following XSLT parameters have been added:</p>
<ul>
<li><codeph>include.rellinks</codeph></li>
</ul>
<p>The following XSLT parameters have been removed:</p>
<ul>
<li><codeph>disableRelatedLinks</codeph></li>
</ul>
</section>
</refbody>
</reference>

80
dita-ot-3.6/docsrc/topics/migrating-to-2.0.dita Normal file
View file

@ -0,0 +1,80 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<reference id="migrating-to-2.0">
<title>Migrating to release 2.0</title>
<titlealts>
<navtitle>To 2.0</navtitle>
</titlealts>
<shortdesc>In DITA-OT 2.0, XSLT templates were converted to XSLT 2.0, variable typing was implemented, and some older
templates were refactored or removed. In addition, the <cmdname>dita</cmdname> command simplifies distribution of
plugins by allowing installation from a URL.<draft-comment author="staylor">There are likely other changes that
should be noted here. See
<xref keyref="2.0-release-notes"/>. </draft-comment>
</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm><xmlatt>as</xmlatt></indexterm>
<indexterm><cmdname>dita</cmdname> command
<indexterm>plug-ins</indexterm></indexterm>
<indexterm>uninstalling</indexterm>
<indexterm>removing
<index-see>uninstalling</index-see></indexterm>
<indexterm>deinstalling
<index-see>uninstalling</index-see></indexterm>
<indexterm>XSLT
<indexterm>2.0</indexterm></indexterm>
<indexterm>Customization directory</indexterm>
</keywords>
</metadata>
</prolog>
<refbody>
<section>
<note>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
<xref keyref="2.0-release-notes"/>.</note>
</section>
<refbodydiv>
<section>
<title>All transformations — variable typing</title>
<p>XSLT stylesheets were converted to XSLT 2.0. With that change, variable types were also implemented. Plug-ins
that change template variable values will need to make the following changes:</p>
<ul>
<li>Declare the same types defined in the default templates with <xmlatt>as</xmlatt>.</li>
<li>Ensure that the generated values conform to the declared type.</li>
</ul>
</section>
<example>
<p>For example:</p>
<codeblock outputclass="language-xml">&lt;xsl:variable name="urltest">
&lt;xsl:variable name="urltest" <b>as="xs:boolean"</b>></codeblock>
</example>
<section>
<title>All transformations — refactoring</title>
<p>Much of the toolkit code was refactored for release 2.0. Customization changes that were based on a specific
template in a previous version of the toolkit might not work because the modified template is no longer used.
If this is the case, the changes will need to be reimplemented based on the new XSLT templates.</p>
</section>
</refbodydiv>
<section>
<title>HTML5</title>
<p>A new <option>HTML5</option> transformation type has been added. Customizations that previously modified the
XHTML output to generate valid HTML5 should still work, but basing your customization on the new transformation
type might simplify the customization and reduce the work required to maintain compatibility with future
versions of the toolkit.</p>
<note>The <option>HTML5</option> transformation was refactored with release 2.2. Before basing your customization
on the changes in release 2.0, consider whether you might want to move to release 2.2 instead. See
<xref keyref="migrating-to-2.2"/>.</note>
</section>
<section>
<title>Plug-in installation and distribution</title>
<p>Plug-ins can now be installed or uninstalled from a ZIP archive using the new <cmdname>dita</cmdname> command.
Plug-ins can also be installed from a referenced URL. See
<xref keyref="dita-command-arguments"/>.</p>
</section>
</refbody>
</reference>

193
dita-ot-3.6/docsrc/topics/migrating-to-2.1.dita Normal file
View file

@ -0,0 +1,193 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<reference id="migrating-to-2.1">
<title>Migrating to release 2.1</title>
<titlealts>
<navtitle>To 2.1</navtitle>
</titlealts>
<shortdesc>In DITA-OT 2.1, the <codeph>insertVariable</codeph> template was deprecated for PDF transformations and
should be replaced with the <codeph>getVariable</codeph> template. Various <codeph>dita.<b>out.</b>map.*</codeph>
targets have been deprecated in favor of updated <codeph>dita.map.*</codeph> equivalents.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm><xmlelement>ph</xmlelement></indexterm>
<indexterm><xmlelement>keyword</xmlelement></indexterm>
<indexterm><xmlelement>cite</xmlelement></indexterm>
<indexterm><xmlelement>dt</xmlelement></indexterm>
<indexterm><xmlelement>term</xmlelement></indexterm>
<indexterm><xmlelement>indexterm</xmlelement></indexterm>
<indexterm><xmlatt>href</xmlatt></indexterm>
<indexterm>deprecated features
<indexterm><codeph>help</codeph> build target</indexterm></indexterm>
<indexterm>deprecated features
<indexterm><parmname>imagefile</parmname></indexterm></indexterm>
<indexterm>deprecated features
<indexterm><codeph>image.list</codeph></indexterm></indexterm>
<indexterm>deprecated features
<indexterm><parmname>htmlfile</parmname></indexterm></indexterm>
<indexterm>deprecated features
<indexterm><codeph>html.list</codeph></indexterm></indexterm>
<indexterm>deprecated features
<indexterm><codeph>copy-subsidiary</codeph> target</indexterm></indexterm>
<indexterm>deprecated features
<indexterm><codeph>copy-subsidiary-check</codeph> target</indexterm></indexterm>
<indexterm>deprecated features
<indexterm><parmname>depend.preprocess.copy-subsidiary.pre</parmname> extension points</indexterm></indexterm>
<indexterm>deprecated features
<indexterm>PDF, <codeph>insertVariable</codeph> template</indexterm></indexterm>
<indexterm>deprecated features
<indexterm><varname>keydefs</varname> variable</indexterm></indexterm>
<indexterm>deprecated features
<indexterm><parmname>KEYREF-FILE</parmname></indexterm></indexterm>
<indexterm>deprecated features
<indexterm><parmname>displaytext</parmname></indexterm></indexterm>
<indexterm>deprecated features
<indexterm><parmname>keys</parmname></indexterm></indexterm>
<indexterm>deprecated features
<indexterm><parmname>target</parmname></indexterm></indexterm>
<indexterm>deprecated features
<indexterm><codeph>pull-in-title</codeph> template</indexterm></indexterm>
<indexterm>deprecated features
<indexterm><codeph>common-processing-phrase-within-link</codeph> template</indexterm></indexterm>
<indexterm>deprecated features
<indexterm><codeph>dita.out.map.xhtml.toc</codeph> target</indexterm></indexterm>
<indexterm>deprecated features
<indexterm><codeph>dita.out.map.htmlhelp.*</codeph> targets</indexterm></indexterm>
<indexterm>deprecated features
<indexterm><codeph>dita.out.map.javahelp.*</codeph> targets</indexterm></indexterm>
<indexterm>deprecated features
<indexterm><parmname>args.odt.img.embed</parmname></indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<refbody>
<section>
<note>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
<xref keyref="2.1-release-notes"/>.</note>
</section>
<section>
<p>The custom<systemoutput>FileUtils</systemoutput> code used to handle input and output in earlier versions of
DITA-OT has been replaced with the
<xref href="http://commons.apache.org/proper/commons-io/" format="html" scope="external">Apache Commons
IO</xref> utilities library. </p>
</section>
<section>
<title>Deprecated targets</title>
<p>The following build targets have been deprecated and will be removed in an upcoming release:</p>
<ul>
<li>The <codeph>help</codeph> target that includes a reference to the current DITA-OT version during the build
process.</li>
</ul>
</section>
<section>
<title>Preprocessing</title>
<p>The following Ant properties and generated list files have been deprecated:</p>
<ul>
<li><parmname>imagefile</parmname> property and <codeph>image.list</codeph> file</li>
<li><parmname>htmlfile</parmname> property and <codeph>html.list</codeph> file</li>
</ul>
<p>The following pre-processing targets and extension points have been deprecated:</p>
<ul>
<li>The <codeph>copy-subsidiary</codeph> target used to copy subsidiary files</li>
<li>The <codeph>copy-subsidiary-check</codeph> target used to check for subsidiary files</li>
<li>The <parmname>depend.preprocess.copy-subsidiary.pre</parmname> extension point used to insert an Ant target
before the <codeph>copy-subsidiary</codeph> step in the pre-processing stage.</li>
</ul>
<p>A new<systemoutput>dita.parser</systemoutput> 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>
<title>PDF</title>
<p>The following template has been deprecated:</p>
<ul>
<li><codeph>insertVariable</codeph>, use <codeph>getVariable</codeph> instead</li>
</ul>
<p>Calls to that template will result in warnings in the build log.</p>
<p>To update your plug-in, make the following changes:</p>
<codeblock
outputclass="language-xml normalize-space show-line-numbers show-whitespace"
>&lt;xsl:call-template name="<line-through>insertVariable</line-through><b>getVariable</b>">
&lt;xsl:with-param name="<line-through>theVariableID</line-through><b>id</b>" select="<varname>var-id</varname>"/>
&lt;xsl:with-param name="<line-through>theParameters</line-through><b>params</b>">
<varname>params</varname>
&lt;/xsl:with-param>
&lt;/xsl:call-template></codeblock>
</section>
<section>
<title>HTML-based output formats</title>
<draft-comment author="Roger" time="2016-04-03 18:30">
<p>Further information required on recommended replacements for deprecated items.</p>
</draft-comment>
<p>The <varname>keydefs</varname> variable and the following XSL parameters have been deprecated:
<ul>
<li><parmname>KEYREF-FILE</parmname></li>
<li><parmname>displaytext</parmname></li>
<li><parmname>keys</parmname></li>
<li><parmname>target</parmname></li>
</ul>
</p>
<p>The following template modes have been deprecated:
<ul>
<li><codeph>pull-in-title</codeph></li>
<li><codeph>common-processing-phrase-within-link</codeph></li>
</ul>
</p>
</section>
<section>
<title>XHTML</title>
<indexterm>keydef</indexterm>
<p>The <codeph>dita.<b>out.</b>map.xhtml.toc</codeph> target has been deprecated and should be replaced with the
updated <codeph>dita.map.xhtml.toc</codeph> equivalent.</p>
<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 <filepath>keydef.xml</filepath>
file to look up targets for phrase elements and pull in text when needed.</p>
<p>This change affects non-linking elements that can’t take <xmlatt>href</xmlatt> attributes, such as
<xmlelement>ph</xmlelement>, <xmlelement>keyword</xmlelement>, <xmlelement>cite</xmlelement>,
<xmlelement>dt</xmlelement>, <xmlelement>term</xmlelement>, and <xmlelement>indexterm</xmlelement> (when
<codeph>$INDEXSHOW</codeph> is active).</p>
</section>
<section>
<title>HTMLHelp</title>
<p>The <codeph>dita.<b>out.</b>map.htmlhelp.*</codeph> targets have been deprecated and should be replaced with
the updated <codeph>dita.map.htmlhelp.*</codeph> equivalents:</p>
<ul>
<li><codeph>dita.out.map.htmlhelp.hhp</codeph>, use <codeph>dita.map.htmlhelp.hhp</codeph> instead</li>
<li><codeph>dita.out.map.htmlhelp.hhc</codeph>, use <codeph>dita.map.htmlhelp.hhc</codeph> instead</li>
<li><codeph>dita.out.map.htmlhelp.hhk</codeph>, use <codeph>dita.map.htmlhelp.hhk</codeph> instead</li>
</ul>
</section>
<section>
<title>JavaHelp</title>
<indexterm>JavaHelp</indexterm>
<p>The <codeph>dita.<b>out.</b>map.javahelp.*</codeph> targets have been deprecated and should be replaced with
the updated <codeph>dita.map.javahelp.*</codeph> equivalents:</p>
<ul>
<li><codeph>dita.out.map.javahelp.toc</codeph>, use <codeph>dita.map.javahelp.toc</codeph> instead</li>
<li><codeph>dita.out.map.javahelp.map</codeph>, use <codeph>dita.map.javahelp.map</codeph> instead</li>
<li><codeph>dita.out.map.javahelp.set</codeph>, use <codeph>dita.map.javahelp.set</codeph> instead</li>
<li><codeph>dita.out.map.javahelp.index</codeph>, use <codeph>dita.map.javahelp.index</codeph> instead</li>
</ul>
</section>
<section>
<title>OpenDocument Text</title>
<p>Support for the <parmname>args.odt.img.embed</parmname> 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>
</refbody>
</reference>

90
dita-ot-3.6/docsrc/topics/migrating-to-2.2.dita Normal file
View file

@ -0,0 +1,90 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<reference id="migrating-to-2.2">
<title>Migrating to release 2.2</title>
<titlealts>
<navtitle>To 2.2</navtitle>
</titlealts>
<shortdesc>In DITA-OT 2.2, the <option>HTML5</option> transformation was refactored as its own plug-in and separate
plug-ins were created for each of the rendering engine-specific PDF transformations.<draft-comment author="staylor">
There are likely other changes that should be noted here. </draft-comment>
</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm><xmlelement>toc</xmlelement></indexterm>
<indexterm><xmlelement>preface</xmlelement></indexterm>
<indexterm><xmlelement>frontmatter</xmlelement></indexterm>
<indexterm><xmlelement>bookmap</xmlelement></indexterm>
<indexterm>deprecated features
<indexterm><codeph>.notetitle</codeph> classes</indexterm></indexterm>
<indexterm>deprecated features
<indexterm><parmname>user.input.file</parmname></indexterm></indexterm>
<indexterm>deprecated features
<indexterm><parmname>user.input.dir</parmname></indexterm></indexterm>
<indexterm>deprecated features
<indexterm><parmname>InputMapDir</parmname></indexterm></indexterm>
<indexterm>RenderX
<indexterm>plug-in</indexterm></indexterm>
<indexterm>Antenna House
<indexterm>plug-in</indexterm></indexterm>
<indexterm>Apache FOP
<indexterm>plug-in</indexterm></indexterm>
<indexterm>table of contents
<indexterm>PDF</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<refbody>
<section>
<note>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
<xref keyref="2.2-release-notes"/>.</note>
</section>
<section>
<title>HTML5</title>
<p>The <option>HTML5</option> transformation introduced in release 2.0 as part of the <option>XHTML</option>
plug-in has been moved to a separate <option>HTML5</option> plug-in. Customizations that extended the previous
HTML5 output under the <option>XHTML</option> plug-in will probably need to be refactored on the new HTML5
plug-in.</p>
<p>Note title processing has been revised to use a common <codeph>note__title</codeph> class for note elements of
all types. The legacy <codeph><varname>{$type}</varname>title</codeph> classes (such as
<codeph>.notetitle</codeph>, <codeph>.cautiontitle</codeph>, <codeph>.tiptitle</codeph>, 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 <codeph>.note_note .note__title</codeph>, <codeph>.note_caution
.note__title</codeph>, <codeph>.note_tip .note__title</codeph>, etc.</p>
</section>
<section>
<title>PDF</title>
<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 <codeph>org.dita.pdf2.fop</codeph>, <codeph>org.dita.pdf2.axf</codeph>, or
<codeph>org.dita.pdf2.xep</codeph> plug-ins.</p>
<p>PDF customizations that are not specific to a rendering engine can continue to extend the
<codeph>org.dita.pdf2</codeph> plug-in as before.</p>
<p>The default format for page numbers in the table of contents (<xmlelement>toc</xmlelement>) was switched to
roman to align with <xmlelement>preface</xmlelement> and ensure consistent numbering styles for all
<xmlelement>frontmatter</xmlelement> components in <xmlelement>bookmap</xmlelement>. 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 <codeph>1,2,3,4,v,vi,7,8</codeph> in this use
case.</p>
</section>
<section>
<title>Deprecated properties</title>
<p>The following Ant properties have been deprecated:
<ul>
<li><parmname>user.input.file</parmname>, use <parmname>user.input.file.uri</parmname> instead to specify the
input file system path</li>
<li><parmname>user.input.dir</parmname>, use <parmname>user.input.dir.uri</parmname> instead to specify the
input directory system path</li>
<li><parmname>InputMapDir</parmname>, use <parmname>InputMapDir.uri</parmname> instead to specify the input
map directory system path</li>
</ul></p>
</section>
</refbody>
</reference>

168
dita-ot-3.6/docsrc/topics/migrating-to-2.3.dita Normal file
View file

@ -0,0 +1,168 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<reference id="migrating-to-2.3">
<title>Migrating to release 2.3</title>
<titlealts>
<navtitle>To 2.3</navtitle>
</titlealts>
<shortdesc>In DITA-OT 2.3, <option>HTML5</option> 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 <codeph>id</codeph> variable that contains the entire message ID.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>languages
<indexterm>supported</indexterm></indexterm>
<indexterm>Chinese</indexterm>
<indexterm>English</indexterm>
<indexterm>Indonesian</indexterm>
<indexterm>Korean</indexterm>
<indexterm>I18N
<indexterm>PDF processing</indexterm></indexterm>
<indexterm>metadata
<indexterm>chunking, effect of</indexterm></indexterm>
<indexterm>tables
<indexterm>HTML5</indexterm></indexterm>
<indexterm>tables
<indexterm>PDF</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<refbody>
<section>
<note>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
<xref keyref="2.3-release-notes"/>.</note>
</section>
<section>
<title>HTML5</title>
<p>The <option>HTML5</option> table processing has been refactored to use valid HTML5 markup, HTML5 best
practices, and better CSS properties for styling.
<xref href="https://en.bem.info/methodology/" format="html" scope="external">BEM</xref>-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>Common CSS files are now generated using separate modules for each DITA domain, implemented as
<xref keyref="sass-lang"/> partials to better support extensions with CSS frameworks, custom plug-ins and future
toolkit versions.</p>
</section>
<section>
<title>HTML-based formats</title>
<indexterm><xmlelement>div</xmlelement>
<indexterm><codeph>div.shortdesc</codeph></indexterm></indexterm>
<indexterm><xmlelement>p</xmlelement></indexterm>
<indexterm><xmlelement>abstract</xmlelement></indexterm>
<indexterm><xmlelement>simpletable</xmlelement></indexterm>
<indexterm><xmlelement>properties</xmlelement></indexterm>
<indexterm><xmlelement>choicetable</xmlelement></indexterm>
<indexterm>deprecated features
<indexterm><codeph>tm-area</codeph> named template</indexterm></indexterm>
<p>The XSLT <codeph>tm-area</codeph> 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 id="2191">In previous releases, short descriptions in <xmlelement>abstract</xmlelement> elements were rendered
as division elements (<xmlelement>div</xmlelement>), rather than paragraphs (<xmlelement>p</xmlelement>).
Processing has been revised to ensure that short descriptions are consistently rendered as paragraphs,
regardless of whether they appear in <xmlelement>abstract</xmlelement> elements. Users who have previously
implemented custom CSS rules to style <codeph>div.shortdesc</codeph> like paragraphs should be able to remove
these rules.</p>
</section>
<section>
<title>PDF</title>
<indexterm>deprecated features
<indexterm><codeph>tm-area</codeph> named template</indexterm></indexterm>
<indexterm>deprecated features
<indexterm>PDF localization variables</indexterm></indexterm>
<indexterm>deprecated features
<indexterm><parmname>conreffile</parmname></indexterm></indexterm>
<indexterm>deprecated features
<indexterm><parmname>conref-check</parmname> target</indexterm></indexterm>
<indexterm>deprecated features
<indexterm><parmname>coderef</parmname> target</indexterm></indexterm>
<p>The <codeph>antiquewhite</codeph> background color has been removed from table heads and key column contents in
<xmlelement>simpletable</xmlelement> and <xmlelement>properties</xmlelement> tables to synchronize
presentation with <xmlelement>choicetable</xmlelement> and provide a more uniform customization baseline between
PDF output and HTML-based formats.</p>
<p id="2179">PDF: The I18N Java and XSLT processing code has been merged into single task. This eliminated the
need for a <filepath>stage3.fo</filepath> file in the temporary directory; instead,
<filepath>topic.fo</filepath> is generated directly from <filepath>stage2.fo</filepath>. If custom plug-ins
were implemented to handle <filepath>stage3.fo</filepath>, they would need to be updated. </p>
<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>
<li>Back button title</li>
<li>Contents button title</li>
<li>Forward button title</li>
<li>Index button title</li>
<li>Index multiple entries separator</li>
<li>Main page button title</li>
<li>Next page button title</li>
<li>Online help prefix</li>
<li>Online Help Search Method And</li>
<li>Online Help Search Method Field</li>
<li>Online Help Search Method Or</li>
<li>Previous page button title</li>
<li>Search button title</li>
<li>Search Case Sensitive Switch</li>
<li>Search Excluded Stop Words Message</li>
<li>Search Highlight Switch</li>
<li>Search index button title</li>
<li>Search index field title</li>
<li>Search index next button title</li>
<li>Search Search Give No Results Message</li>
<li>Search Search in Progress Message</li>
<li>Search Stopped Message</li>
<li>Search text button title</li>
<li>Search text field title</li>
<li>Search title</li>
<li>Search Whole Words Switch</li>
<li>Untitled section</li>
</ul>
</p>
<note>Most of these variables were never used by the PDF process, and most were not supported (or localized) for
any language other than English.</note>
</section>
<section>
<title>Deprecated properties and targets</title>
<p>The following Ant properties have been deprecated:
<ul>
<li><parmname>conreffile</parmname></li>
</ul>
</p>
<p>The following preprocessing targets have been deprecated:
<ul>
<li><parmname>conref-check</parmname></li>
<li><parmname>coderef</parmname></li>
</ul>
</p>
</section>
<section>
<title>Pre-processing</title>
<p id="2207">The order of the <codeph>chunk</codeph> and <codeph>move-meta-entries</codeph> pre-processing stages
has been switched so that <codeph>chunk</codeph> comes first. This ensures that metadata is properly pulled or
pushed into the chunked version of DITA topics. </p>
</section>
<section>
<title>Generating error messages</title>
<p>Previously, the XSLT <codeph>output-message</codeph> named template for generating error messages combined a
global <codeph>msgprefix</codeph> variable and two parameters to determine the actual message ID. This function
has been updated to use a single <codeph>id</codeph> variable that contains the entire message ID.</p>
<p>Plug-ins that make use of the <codeph>output-message</codeph> function should be updated to use the single
<codeph>id</codeph> variable, as
in:<codeblock
outputclass="language-xml normalize-space show-line-numbers show-whitespace"
>&lt;xsl:call-template name="output-message">
&lt;xsl:with-param name="id" select="'FULLMESSAGENUMBER'"/>
&lt;xsl:with-param name="msgparams">optional-message-parameters&lt;/xsl:with-param>
&lt;/xsl:call-template></codeblock>
</p>
<p>The <codeph>msgprefix</codeph> XSL variable (“DOTX”) has been deprecated and will be removed in an upcoming
release.</p>
</section>
</refbody>
</reference>

116
dita-ot-3.6/docsrc/topics/migrating-to-2.4.dita Normal file
View file

@ -0,0 +1,116 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<reference id="migrating-to-2.4">
<title>Migrating to release 2.4</title>
<titlealts>
<navtitle>To 2.4</navtitle>
</titlealts>
<shortdesc>In DITA-OT 2.4, the <option>HTML5</option> transformation was refactored as an independent plug-in that no
longer depends on the <option>XHTML</option> plug-in. </shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>deprecated features
<indexterm><codeph>.notetitle</codeph> classes</indexterm></indexterm>
<indexterm>GitHub</indexterm>
</keywords>
</metadata>
</prolog>
<refbody>
<section>
<note>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
<xref keyref="2.4-release-notes"/>.</note>
</section>
<section>
<title>HTML5</title>
<ul>
<li>
<div id="24-html5-split">
<p>The <option>HTML5</option> transformation introduced in release 2.0 as part of the <option>XHTML</option>
plug-in was moved to a separate <option>HTML5</option> plug-in in release 2.2, but that version of the
<option>HTML5</option> transformation still depended on the <option>XHTML</option> plug-in for certain
common processing.</p>
<p>In release 2.4, all dependencies between <option>HTML5</option> and <option>XHTML</option> 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 <option>eclipsehelp</option>,
<option>htmlhelp</option> or <option>javahelp</option>.</p>
</div>
<p>Customizations that extended the previous HTML5 output under the <option>XHTML</option> plug-in (as
provided in releases 2.0 and 2.1) or the <option>HTML5</option> plug-in that shipped with release 2.2 will
need to be refactored to build on the new HTML5 plug-in.</p></li>
<li>
<p>Note title processing was revised in release 2.2 to include a common <codeph>note__title</codeph> class for
note elements of all types. The legacy <codeph><varname>{$type}</varname>title</codeph> classes (such as
<codeph>.notetitle</codeph>, <codeph>.cautiontitle</codeph>, <codeph>.tiptitle</codeph>, etc.) were
included in release 2.2 for backwards compatibility, but have now been removed in release 2.4.</p>
<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>
<li><codeph>.note_note .note__title</codeph></li>
<li><codeph>.note_caution .note__title</codeph></li>
<li><codeph>.note_tip .note__title</codeph></li>
</ul>
</li>
</ul>
</section>
<section id="24-legacy-plugin-removal">
<title>Legacy plug-ins removed</title>
<indexterm>DocBook</indexterm>
<indexterm>Eclipse Content</indexterm>
<indexterm>OpenDocument Text</indexterm>
<indexterm>RTF</indexterm>
<indexterm>plug-ins
<indexterm>DocBook</indexterm></indexterm>
<indexterm>plug-ins
<indexterm>Eclipse Content</indexterm></indexterm>
<indexterm>plug-ins
<indexterm>OpenDocument Text</indexterm></indexterm>
<indexterm>plug-ins
<indexterm>RTF</indexterm></indexterm>
<p>DITA-OT 2.4 no longer includes the following legacy transformation plug-ins in the default distribution:</p>
<table outputclass="table-hover" frame="none" colsep="0" rowsep="1">
<title>Legacy plug-ins</title>
<tgroup cols="2">
<colspec colwidth="1*"/>
<colspec colwidth="1*"/>
<thead>
<row>
<entry>Plug-in </entry>
<entry>Source code location</entry>
</row>
</thead>
<tbody>
<row>
<entry>DocBook</entry>
<entry>
<xref href="https://github.com/dita-ot/org.dita.docbook" format="html" scope="external"/></entry>
</row>
<row>
<entry>Eclipse Content</entry>
<entry>
<xref href="https://github.com/dita-ot/org.dita.eclipsecontent" format="html" scope="external"/></entry>
</row>
<row>
<entry>OpenDocument Text</entry>
<entry>
<xref href="https://github.com/dita-ot/org.dita.odt" format="odt" scope="external"/></entry>
</row>
<row>
<entry>Word RTF</entry>
<entry>
<xref href="https://github.com/dita-ot/org.dita.wordrtf" format="html" scope="external"/></entry>
</row>
</tbody>
</tgroup>
</table>
<note conkeyref="reusable-components/legacy-plugins-note"/>
</section>
</refbody>
</reference>

103
dita-ot-3.6/docsrc/topics/migrating-to-2.5.dita Normal file
View file

@ -0,0 +1,103 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<reference id="migrating-to-2.5">
<title>Migrating to release 2.5</title>
<titlealts>
<navtitle>To 2.5</navtitle>
</titlealts>
<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.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm><xmlelement>example</xmlelement></indexterm>
<indexterm>PDF
<indexterm><codeph>org.dita.pdf2.legacy</codeph></indexterm></indexterm>
<indexterm>languages
<indexterm>right-to-left</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<refbody>
<section>
<note>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
<xref keyref="2.5-release-notes"/>.</note>
</section>
<section>
<title>Deprecated logging parameters</title>
<p>The <codeph>args.debug</codeph> and <codeph>args.logdir</codeph> properties have been deprecated and will be
removed in an upcoming version of DITA-OT.</p>
<ul>
<li>
<p>To enable debug logging, use <cmdname>dita</cmdname>
<parmname>--debug</parmname>.</p>
<note type="attention">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.</note>
</li>
<li>
<p>To write the log to a file, use <cmdname>dita</cmdname>
<parmname>--logfile</parmname>=<varname>file</varname> or <cmdname>ant</cmdname>
<parmname>-l</parmname>
<varname>file</varname> and specify the path to the log file.</p>
<p>Unless an absolute path is specified, the value will be interpreted relative to the current
directory.</p></li>
</ul>
</section>
<section id="25-pdf-changes">
<title>Default PDF style improvements</title>
<indexterm>tables
<indexterm>indentation</indexterm></indexterm>
<p>Several legacy styles have been modified or removed in the default PDF plug-in <codeph>org.dita.pdf2</codeph>,
including the following:</p>
<p>
<ul>
<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>Table containers now inherit the initial indentation (<codeph>start-indent</codeph>) from the parent
elements.</li>
<li>Borders and indentation have been removed from <xmlelement>example</xmlelement> elements.</li>
<li>Links are no longer italicized.</li>
<li>Titles for related link lists have been standardized to use the <codeph>common.title</codeph> attribute
set (which applies the <codeph>sans-serif</codeph> font-family) and bold font weight.</li>
<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>
</p></section>
<section id="25-legacy-pdf-plugin">
<title>External plug-in for legacy PDF styling</title>
<p>If you have a custom PDF plug-in that explicitly depends on the previous default settings for the
aforementioned styles, the <codeph>org.dita.pdf2.legacy</codeph> plug-in can be used to restore the pre–2.5
styles.</p>
<table outputclass="table-hover" frame="none" colsep="0" rowsep="1">
<tgroup cols="2">
<colspec colwidth="1*"/>
<colspec colwidth="1*"/>
<thead>
<row>
<entry>Plug-in </entry>
<entry>Source code location</entry>
</row>
</thead>
<tbody>
<row>
<entry><codeph>org.dita.pdf2.legacy</codeph></entry>
<entry>
<xref href="https://github.com/dita-ot/org.dita.pdf2.legacy" format="html" scope="external"/></entry>
</row>
</tbody>
</tgroup>
</table>
<p>To install the legacy PDF plug-in, run the following command:</p>
<codeblock><cmdname>dita</cmdname> <parmname>--install</parmname>=<filepath
>https://github.com/dita-ot/org.dita.pdf2.legacy/archive/2.5.zip</filepath></codeblock>
<note type="attention">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.</note>
</section>
</refbody>
</reference>

87
dita-ot-3.6/docsrc/topics/migrating-to-3.0.dita Normal file
View file

@ -0,0 +1,87 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<reference id="migrating-to-3.0">
<title>Migrating to release 3.0</title>
<titlealts>
<navtitle>To 3.0</navtitle>
</titlealts>
<shortdesc>DITA-OT 3.0 <ph id="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 <codeph>preprocess</codeph> operation.</ph></shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>Lightweight DITA</indexterm>
<indexterm>GitHub</indexterm>
</keywords>
</metadata>
</prolog>
<refbody>
<section>
<note>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
<xref keyref="3.0-release-notes"/>.</note>
</section>
<section conkeyref="reusable-components/use-xslt2"/>
<section id="30-legacy-plugin-removal">
<title>Legacy plug-ins removed</title>
<indexterm>JavaHelp</indexterm>
<indexterm>deprecated features
<indexterm>JavaHelp plug-in</indexterm></indexterm>
<indexterm>plug-ins
<indexterm>JavaHelp</indexterm></indexterm>
<p>DITA-OT 3.0 no longer includes the following legacy transformation plug-ins in the default distribution:</p>
<table outputclass="table-hover" frame="none" colsep="0" rowsep="1">
<title>Legacy plug-ins</title>
<tgroup cols="2">
<colspec colwidth="1*"/>
<colspec colwidth="1*"/>
<thead>
<row>
<entry>Plug-in </entry>
<entry>Source code location</entry>
</row>
</thead>
<tbody>
<row>
<entry>JavaHelp
<indexterm>JavaHelp</indexterm></entry>
<entry>
<xref href="https://github.com/dita-ot/org.dita.javahelp" format="html" scope="external"/></entry>
</row>
</tbody>
</tgroup>
</table>
<note conkeyref="reusable-components/legacy-plugins-note"/>
<p>To re-install the JavaHelp plug-in, run the following command:</p>
<codeblock><cmdname>dita</cmdname> <parmname>--install</parmname>=<filepath
>https://github.com/dita-ot/org.dita.javahelp/archive/2.5.zip</filepath></codeblock>
</section>
<section id="map-first">
<title>Map-first preprocessing</title>
<p><ph conkeyref="map-first-preproc/map-first-preproc-desc"/></p>
<p conkeyref="reusable-components/no-internal-preprocess2-ext"/>
<note type="tip">See
<xref keyref="map-first-preproc"/> for information on how to use (or test) map-first preprocessing, or revert to
the default <codeph>preprocess</codeph> target.</note>
</section>
<section>
<title>New <codeph>ant.import</codeph> extension point</title>
<p>A new extension point has been added to make it easier to add new targets to the Ant processing pipeline.</p>
<p>Earlier versions of DITA-OT use the <codeph>dita.conductor.target.relative</codeph> 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 <codeph>ant.import</codeph> approach should be used for all new customizations. </p>
<note type="tip">See
<xref keyref="plugin-anttarget"/> for details.</note>
</section>
</refbody>
</reference>

101
dita-ot-3.6/docsrc/topics/migrating-to-3.1.dita Normal file
View file

@ -0,0 +1,101 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<reference id="migrating-to-3.1">
<title>Migrating to release 3.1</title>
<titlealts>
<navtitle>To 3.1</navtitle>
</titlealts>
<shortdesc>DITA-OT 3.1 includes <ph id="summary">support for DITA 1.3 SVG domain elements, enhanced
<xmlelement>codeblock</xmlelement> processing, and incremental improvements to Lightweight DITA processing and
PDF output</ph>.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm><xmlelement>codeblock</xmlelement></indexterm>
<indexterm><xmlelement>param</xmlelement></indexterm>
<indexterm><xmlatt>if:set</xmlatt></indexterm>
<indexterm><xmlatt>unless:set</xmlatt></indexterm>
<indexterm><xmlatt>if</xmlatt></indexterm>
<indexterm><xmlatt>outputclass</xmlatt></indexterm>
<indexterm>deprecated features
<indexterm><codeph>dost.class.path</codeph> property</indexterm></indexterm>
<indexterm>deprecated features
<indexterm><codeph>xml.catalog.files</codeph> property</indexterm></indexterm>
<indexterm>deprecated features
<indexterm><codeph>dost.class.path</codeph></indexterm></indexterm>
<indexterm>Lightweight DITA</indexterm>
<indexterm>XSLT
<indexterm>Ant</indexterm></indexterm>
<indexterm>DITA 1.3
<indexterm>SVG domain</indexterm></indexterm>
<indexterm>SVG</indexterm>
<indexterm>catalog
<indexterm><codeph>xml.catalog.files</codeph></indexterm>
<indexterm><codeph>xml.catalog.path</codeph></indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<refbody>
<section>
<note>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
<xref keyref="3.1-release-notes"/>.</note>
</section>
<section>
<title>Custom if/unless attributes in Ant scripts</title>
<p>Ant scripts for DITA-OT builds now make use of <xmlatt>if:set</xmlatt> and <xmlatt>unless:set</xmlatt>
attributes in the Ant namespace, which can be used to control whether parameters are passed to XSLT modules.
These attributes replace custom implementations of <codeph>if</codeph> and <codeph>unless</codeph> logic
introduced before Ant had this capability.</p>
<p>If your plug-ins include Ant scripts that use <xmlatt>if</xmlatt> or <xmlatt>unless</xmlatt> on
<xmlelement>param</xmlelement> elements that pass XSLT parameters, add the following namespace attributes to
the root project:
<ul>
<li><xmlnsname>xmlns:if</xmlnsname>=<codeph>"ant:if"</codeph></li>
<li><xmlnsname>xmlns:unless</xmlnsname>=<codeph>"ant:unless"</codeph></li>
</ul></p>
<p>In custom Ant build files and in any files that supply parameters to existing DITA-OT XSLT modules, replace all
occurrences of <codeph>if="property"</codeph> on <xmlelement>param</xmlelement> elements with
<codeph>if<b>:set</b>="property"</codeph> (and <codeph>unless</codeph> → <codeph>unless<b>:set</b></codeph>
respectively).</p>
<p><codeblock
outputclass="language-xml normalize-space show-line-numbers show-whitespace"
>&lt;root xmlns:if="ant:if" xmlns:unless="ant:unless">
&lt;param name="antProperty" expression="${antProperty}"
if<b>:set</b>="antProperty"/>
&lt;/root></codeblock></p>
<p>For more information on passing parameters to existing XSLT steps, see
<xref keyref="plugin-extension-points-xslt-parameters"/>.</p>
</section>
<section>
<title>Deprecated properties</title>
<sectiondiv>
<!-- From plugin-javalib.dita -->
<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
<codeph>dost.class.path</codeph> 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 <codeph>dita.conductor.lib.import</codeph> extension point to
integrate its JAR dependencies you must add it.</p>
<p>The effective DITA-OT class path is the combination of the JAR files in the main <filepath>lib/</filepath>
directory and the plug-in-contributed JARs, which are listed in <filepath>config/env.sh</filepath>. The
<filepath>env.sh</filepath> file is updated automatically when plug-ins are installed or removed.</p>
</sectiondiv>
<p>The <codeph>xml.catalog.files</codeph> property has been deprecated and should not be used. Replace any such
references with the <codeph>xml.catalog.path</codeph> instead.</p>
</section>
<section id="pdf-line-numbers">
<title>PDF – Enabling line numbers in codeblocks </title>
<p>The <codeph>codeblock.generate-line-number</codeph> template mode default has been changed to check for the
<codeph>show-line-numbers</codeph> keyword in the <xmlatt>outputclass</xmlatt> attribute. Earlier versions of
DITA-OT required custom PDF plug-ins to override the template mode to return <codeph>true()</codeph>. </p>
</section>
</refbody>
</reference>

62
dita-ot-3.6/docsrc/topics/migrating-to-3.2.dita Normal file
View file

@ -0,0 +1,62 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<reference id="migrating-to-3.2">
<title>Migrating to release 3.2</title>
<titlealts>
<navtitle>To 3.2</navtitle>
</titlealts>
<shortdesc>DITA-OT 3.2 includes <ph id="summary">new command-line options, support for RELAX NG parsing and
validation, preliminary processing for the XDITA authoring format proposed for Lightweight DITA, and a plug-in
registry that makes it easier to discover and install new plug-ins</ph>.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>deprecated features
<indexterm><parmname>configuration-jar</parmname> Ant target</indexterm></indexterm>
<indexterm>Lightweight DITA</indexterm>
<indexterm>command line
<indexterm>RELAX NG parsing</indexterm></indexterm>
<indexterm>security</indexterm>
<indexterm>TLS</indexterm>
<indexterm>registry</indexterm>
<indexterm>targets
<indexterm>deprecated</indexterm></indexterm>
<indexterm>classpath
<indexterm><parmname>configuration-jar</parmname></indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<refbody>
<section>
<note>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
<xref keyref="3.2-release-notes"/>.</note>
</section>
<section>
<title>Deprecated targets</title>
<p>The <parmname>configuration-jar</parmname> 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 <filepath>lib/dost-configuration.jar</filepath>, but recent versions of
DITA-OT include the <filepath>config</filepath> directory in the classpath for this purpose, so the
configuration JAR is no longer necessary.</p>
</section>
<section>
<title>Secure connections to the plug-in registry</title>
<note type="attention">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 <codeph>registry</codeph> key in the
<filepath>config/configuration.properties</filepath> file to switch the URI schema to
<codeph>http<b>s</b>://</codeph>, so the entry reads <codeph>https://plugins.dita-ot.org/</codeph>.</note>
<p>For more information, see
<xref keyref="plugins-registry"/>.</p>
</section>
</refbody>
</reference>

121
dita-ot-3.6/docsrc/topics/migrating-to-3.3.dita Normal file
View file

@ -0,0 +1,121 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<reference id="migrating-to-3.3">
<title>Migrating to release 3.3</title>
<titlealts>
<navtitle>To 3.3</navtitle>
</titlealts>
<shortdesc>DITA-OT 3.3 includes <ph id="summary">new attribute sets for HTML5 customization, support for custom
integration processing, rotated table cells in PDF output, and hazard statements in HTML output</ph>.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>security</indexterm>
<indexterm>TLS</indexterm>
<indexterm>registry</indexterm>
<indexterm>tables
<indexterm>PDF</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<refbody>
<section>
<note>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
<xref keyref="3.3-release-notes"/>.</note>
</section>
<section>
<title>Secure connections to the plug-in registry</title>
<note type="attention">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 <codeph>registry</codeph> key in the
<filepath>config/configuration.properties</filepath> file to switch the URI schema to
<codeph>http<b>s</b>://</codeph>, so the entry reads <codeph>https://plugins.dita-ot.org/</codeph>.</note>
<p>For more information, see
<xref keyref="plugins-registry"/>.</p>
</section>
<section>
<title>Base plug-in files moved to <filepath>plugins</filepath> directory</title>
<indexterm><xmlelement>xsl:include</xmlelement></indexterm>
<indexterm><xmlelement>xsl:import</xmlelement></indexterm>
<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 <filepath>plugins/org.dita.base</filepath>.</p>
<note type="attention">There is no longer an <filepath>xsl/</filepath> directory in the installation root.</note>
<p>If your plug-ins use the <codeph>plugin</codeph> URI scheme as recommended in the
<xref keyref="plugin-coding-conventions"/>, this change should not require any modifications to custom plug-in
code:</p>
<lq>
<p>In XSLT, use the <codeph>plugin</codeph> URI scheme in <xmlelement>xsl:import</xmlelement> and
<xmlelement>xsl:include</xmlelement> to reference files in other plug-ins.</p>
<p>Instead of:</p>
<p><codeblock
outputclass="language-xml"
>&lt;xsl:import href="../../org.dita.base/xsl/common/output-message.xsl"/></codeblock></p>
<p>use:</p>
<p><codeblock
outputclass="language-xml"
>&lt;xsl:import href="plugin:org.dita.base:xsl/common/output-message.xsl"/></codeblock></p>
<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
<codeph>plugin:<varname>plugin-id</varname>:<varname>path/within/plugin/file.xsl</varname></codeph>.</p>
</lq>
</section>
<section>
<title>Relocated catalog</title>
<indexterm><xmlelement>nextCatalog</xmlelement></indexterm>
<indexterm>catalog
<indexterm>location</indexterm></indexterm>
<p>
<ph id="catalog">Along with the other base plug-in files, the <filepath>catalog-dita.xml</filepath> file has
been moved from the root of the DITA-OT installation directory to <filepath>plugins/org.dita.base</filepath>.
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
<codeph>${dita.plugin.org.dita.base.dir}/catalog-dita.xml</codeph>. A placeholder with a
<xmlelement>nextCatalog</xmlelement> entry is provided in the original location for backwards compatibility,
but this file may be removed in an upcoming release.</ph></p>
<fig>
<title>Legacy catalog placeholder content</title>
<codeblock
outputclass="language-xml"
>&lt;nextCatalog catalog="plugins/org.dita.base/catalog-dita.xml"/></codeblock>
</fig>
</section>
<section>
<title>Deprecated properties</title>
<indexterm><xmlelement>template</xmlelement></indexterm>
<indexterm>deprecated features
<indexterm><filepath>plugin.xml</filepath>, <codeph>templates</codeph> key</indexterm></indexterm>
<p><ph id="templates">The <codeph>templates</codeph> key in configuration properties has been deprecated in favor
of the <xmlelement>template</xmlelement> element in <filepath>plugin.xml</filepath>.</ph></p>
</section>
<section>
<title>New attribute sets for HTML5 customization</title>
<indexterm>Bootstrap</indexterm>
<indexterm>CSS
<indexterm>HTML5</indexterm></indexterm>
<indexterm>HTML5
<indexterm>CSS</indexterm></indexterm>
<p id="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>
<li><codeph>article</codeph></li>
<li><codeph>banner</codeph></li>
<li><codeph>footer</codeph></li>
<li><codeph>main</codeph></li>
<li><codeph>navigation</codeph></li>
<li><codeph>toc</codeph></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.</p>
</section>
</refbody>
</reference>

98
dita-ot-3.6/docsrc/topics/migrating-to-3.4.dita Normal file
View file

@ -0,0 +1,98 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<reference id="migrating-to-3.4">
<title>Migrating to release 3.4</title>
<titlealts>
<navtitle>To 3.4</navtitle>
</titlealts>
<shortdesc>DITA-OT 3.4 includes <ph id="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</ph>.</shortdesc>
<refbody>
<section>
<note>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
<xref keyref="3.4-release-notes"/>.</note>
</section>
<section>
<title>New indexing plug-in</title>
<sectiondiv id="indexing-plugin">
<p>DITA-OT 3.4 extracts the PDF indexing code to a separate <filepath>org.dita.index</filepath> plug-in, and
adds a new <codeph>depend.org.dita.pdf2.index</codeph> extension point that can be used to add custom index
processing targets to PDF output.</p>
<p>The built-in index processing has been disabled and deprecated. If you have overridden index processing via
the <codeph>transform.topic2fo</codeph> target in the past, you can set the new
<parmname>org.dita.index.skip</parmname> property to <option>yes</option> and re-enable the
<codeph>transform.topic2fo.index</codeph> target with <xmlelement>feature
extension="depend.org.dita.pdf2.index" value="transform.topic2fo.index"/</xmlelement> in your plug-in
configuration.</p>
</sectiondiv>
<table outputclass="table-hover" frame="none" colsep="0" rowsep="1">
<title>New plug-ins</title>
<tgroup cols="2">
<colspec colwidth="1*"/>
<colspec colwidth="1*"/>
<thead>
<row>
<entry>Plug-in </entry>
<entry>Source code location</entry>
</row>
</thead>
<tbody>
<row>
<entry>org.dita.index</entry>
<entry>
<xref href="https://github.com/dita-ot/org.dita.index" format="html" scope="external"/></entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section id="34-legacy-plugin-removal">
<title>Legacy plug-ins removed</title>
<indexterm>TocJS</indexterm>
<indexterm>deprecated features
<indexterm>TocJS plug-in</indexterm></indexterm>
<indexterm>plug-ins
<indexterm>TocJS</indexterm></indexterm>
<p>DITA-OT 3.4 no longer includes the following legacy transformation plug-ins in the default distribution:</p>
<table outputclass="table-hover" frame="none" colsep="0" rowsep="1">
<title>Legacy plug-ins</title>
<tgroup cols="2">
<colspec colwidth="1*"/>
<colspec colwidth="1*"/>
<thead>
<row>
<entry>Plug-in </entry>
<entry>Source code location</entry>
</row>
</thead>
<tbody>
<row>
<entry>TocJS</entry>
<entry>
<xref href="https://github.com/dita-ot/com.sophos.tocjs" format="html" scope="external"/></entry>
</row>
<row>
<entry>troff</entry>
<entry>
<xref href="https://github.com/dita-ot/org.dita.troff" format="html" scope="external"/></entry>
</row>
</tbody>
</tgroup>
</table>
<note conkeyref="reusable-components/legacy-plugins-note"/>
<p>To re-install the plug-in(s) from the plug-in registry at
<xref keyref="site-plugin-registry"/>, run the following command(s):</p>
<codeblock outputclass="syntax-bash"><cmdname>dita</cmdname> <parmname>--install</parmname>=<filepath
>com.sophos.tocjs</filepath>
<cmdname>dita</cmdname> <parmname>--install</parmname>=<filepath>org.dita.troff</filepath></codeblock>
</section>
</refbody>
</reference>

156
dita-ot-3.6/docsrc/topics/migrating-to-3.5.dita Normal file
View file

@ -0,0 +1,156 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<reference id="migrating-to-3.5">
<title>Migrating to release 3.5</title>
<titlealts>
<navtitle>To 3.5</navtitle>
</titlealts>
<shortdesc>DITA-OT 3.5 includes <ph id="summary">support for additional input resources, an alternative subcommand
syntax for the <cmdname>dita</cmdname> command, and an initial preview of features for the latest draft of the
upcoming DITA 2.0 standard</ph>.</shortdesc>
<refbody>
<section>
<note>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
<xref keyref="3.5-release-notes"/>.</note>
</section>
<section id="subcommands">
<title>New subcommands</title>
<p>The <cmdname>dita</cmdname> command line interface has been refactored to support subcommands for common
operations.</p>
<note type="important">The new subcommands supersede the deprecated X-Toolkit–style single-hyphen keyword variants
(such as <option>-install</option>), and the corresponding GNU-style option keywords preceded by two hyphens
(such as <option>--install</option>).</note>
<dl>
<dlentry conkeyref="reusable-components/install-subcommand" conrefend="default.dita#ID/version-subcommand">
<dt/>
<dd/>
</dlentry>
</dl>
<note type="tip">The double-hyphen option syntax has been retained for backwards compatibility, so if you use
commands like <cmdname>dita</cmdname>
<parmname>--install</parmname> in scripts, they will still work, but you may want to migrate your scripts to the
new subcommand syntax.</note>
</section>
<section id="3.5-legacy-target-removal">
<title>Legacy constructs removed</title>
<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>The following Ant targets have been removed from the pre-processing pipeline:</p>
<ul>
<li><codeph>mappull</codeph> and <codeph>mappull-check</codeph>, which were used to pull metadata (such as
navtitle) into the map from referenced topics prior to DITA-OT 2.2 (merged with
<codeph>move-meta-entries</codeph>)</li>
<li><codeph>conref-check</codeph>, deprecated since 2.3</li>
<li><codeph>coderef</codeph>, which was used to resolve code references in input files prior to 2.3 (merged with
<codeph>topic-fragment</codeph>)</li>
<li><codeph>copy-subsidiary</codeph> and <codeph>copy-subsidiary-check</codeph>, which were used to copy files
to the temporary directory prior to 2.1</li>
</ul>
<p>Recent DITA-OT versions provide alternative mechanisms to achieve the same results, such as the
<xmlelement>ditafileset</xmlelement> element to select resources in the temporary directory.</p>
<p>Along with the obsolete targets, the following Ant properties have been removed:</p>
<ul>
<li><codeph>canditopicsfile</codeph></li>
<li><codeph>canditopicslist</codeph></li>
<li><codeph>conreffile</codeph></li>
<li><codeph>conreflist</codeph></li>
<li><codeph>conreftargetsfile</codeph></li>
<li><codeph>conreftargetslist</codeph></li>
<li><codeph>copytosourcefile</codeph></li>
<li><codeph>copytosourcelist</codeph></li>
<li><codeph>fullditamapandtopicfile</codeph></li>
<li><codeph>fullditamapandtopiclist</codeph></li>
<li><codeph>fullditamapfile</codeph></li>
<li><codeph>fullditamaplist</codeph></li>
<li><codeph>fullditatopicfile</codeph></li>
<li><codeph>fullditatopiclist</codeph></li>
<li><codeph>hrefditatopicfile</codeph></li>
<li><codeph>hrefditatopiclist</codeph></li>
<li><codeph>hreftargetsfile</codeph></li>
<li><codeph>hreftargetslist</codeph></li>
<li><codeph>htmlfile</codeph></li>
<li><codeph>htmllist</codeph></li>
<li><codeph>imagefile</codeph></li>
<li><codeph>imagelist</codeph></li>
<li><codeph>outditafilesfile</codeph></li>
<li><codeph>outditafileslist</codeph></li>
<li><codeph>resourceonlyfile</codeph></li>
<li><codeph>resourceonlylist</codeph></li>
<li><codeph>subjectschemefile</codeph></li>
<li><codeph>subjectschemelist</codeph></li>
<li><codeph>subtargetsfile</codeph></li>
<li><codeph>subtargetslist</codeph></li>
<li><codeph>user.input.file.listfile</codeph></li>
<li><codeph>user.input.file</codeph></li>
</ul>
<p>The following obsolete list files are no longer generated in the temporary directory:</p>
<ul>
<li><filepath>canditopics.list</filepath></li>
<li><filepath>conref.list</filepath></li>
<li><filepath>conreftargets.list</filepath></li>
<li><filepath>copytosource.list</filepath></li>
<li><filepath>fullditamap.list</filepath></li>
<li><filepath>fullditamapandtopic.list</filepath></li>
<li><filepath>fullditatopic.list</filepath></li>
<li><filepath>hrefditatopic.list</filepath></li>
<li><filepath>hreftargets.list</filepath></li>
<li><filepath>html.list</filepath></li>
<li><filepath>image.list</filepath></li>
<li><filepath>outditafiles.list</filepath></li>
<li><filepath>resourceonly.list</filepath></li>
<li><filepath>subjectscheme.list</filepath></li>
<li><filepath>subtargets.list</filepath></li>
<li><filepath>user.input.file.list</filepath></li>
<li><filepath>usr.input.file.list</filepath></li>
</ul>
<p>For example, if your plug-in previously used the <codeph>fullditatopicfile</codeph> to select resources in the
temporary directory like this:</p>
<codeblock
outputclass="language-xml normalize-space show-line-numbers show-whitespace"
>&lt;xslt basedir="${dita.temp.dir}"
destdir="${output.dir}"
includesfile="${dita.temp.dir}${file.separator}${fullditatopicfile}"
style="${args.xsl}">
&lt;!-- ⋮ -->
&lt;/xslt></codeblock>
<p> With DITA-OT 2.4 or newer, use the <xmlelement>ditafileset</xmlelement> element instead: </p>
<codeblock
outputclass="language-xml normalize-space show-line-numbers show-whitespace"
>&lt;xslt basedir="${dita.temp.dir}"
destdir="${output.dir}"
style="${args.xsl}">
&lt;ditafileset format="dita" processingRole="normal"/>
&lt;!-- ⋮ -->
&lt;/xslt></codeblock>
<p>If your plug-in previously used the <codeph>user.input.file.listfile</codeph> to process the start map like
this:</p>
<codeblock outputclass="language-xml normalize-space show-line-numbers show-whitespace">&lt;xslt …
includesfile="${dita.temp.dir}${file.separator}${user.input.file.listfile}"/></codeblock>
<p>Use the <xmlelement>ditafileset</xmlelement> element as follows:</p>
<codeblock outputclass="language-xml normalize-space show-line-numbers show-whitespace">&lt;xslt … >
&lt;ditafileset input="true" format="ditamap"/>
&lt;/xslt></codeblock>
</section>
<section id="rewriting-output-files">
<title>Adjusting output file names</title>
<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 (<codeph>preprocess2</codeph>).</p>
<p>These parameters can be passed on the command line, or included in a custom plug-in via
<xmlelement>property</xmlelement> elements in an Ant script as described in
<xref keyref="plugin-rewrite-rules"/>.
<ul>
<li>Use <parmname>result.rewrite-rule.class</parmname> to rewrite filenames with a Java class that implements
the <codeph>org.dita.dost.module.RewriteRule</codeph> interface</li>
<li>Use <parmname>result.rewrite-rule.xsl</parmname> to rewrite via an XSLT stylesheet</li>
</ul>
</p>
</section>
</refbody>
</reference>

110
dita-ot-3.6/docsrc/topics/migrating-to-3.6.dita Normal file
View file

@ -0,0 +1,110 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<reference id="migrating-to-3.6">
<title>Migrating to release 3.6</title>
<titlealts>
<navtitle>To 3.6</navtitle>
</titlealts>
<shortdesc>DITA-OT 3.6 includes <ph id="summary">performance enhancements such as processing in parallel and in
memory, support for PDF changebars with <tm trademark="Apache" tmtype="tm">Apache</tm> FOP, and an updated preview
of features for the latest draft of the upcoming DITA 2.0 standard, including the <xmlelement>audio</xmlelement>
and <xmlelement>video</xmlelement> elements, and the new emphasis domain</ph>.</shortdesc>
<refbody>
<section>
<note>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
<xref keyref="3.6-release-notes"/>.</note>
</section>
<section id="parallel-processing">
<title>Parallel processing</title>
<indexterm>parallel processing</indexterm>
<p>Preprocessing module code can now be run in parallel by setting the <parmname>parallel</parmname> parameter to
<option>true</option>. 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 id="in-memory-processing">
<title>In-memory processing</title>
<indexterm>in-memory processing</indexterm>
<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 <parmname>store-type</parmname> parameter to <option>memory</option>.
<ph id="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.</ph> For more information, see
<xref keyref="store-api"/>.</p>
</section>
<section>
<title>Caching DITA class instances</title>
<p>The DITA-OT Java code uses a new caching <codeph>DitaClass.getInstance(cls)</codeph> factory method rather than
generating <codeph>DitaClass</codeph> instances directly. This allows previously created instances to be
re-used, which reduces the number of instances that need to be created.</p>
<note type="important">Custom plug-ins that use the <codeph>DitaClass</codeph> constructor in Java code should be
updated to use the <codeph>getInstance</codeph> factory method instead.</note>
</section>
<section id="fop-changebars">
<title>PDF changebars with <tm trademark="Apache" tmtype="tm">Apache</tm> FOP</title>
<indexterm>Apache FOP
<indexterm>change bars</indexterm></indexterm>
<indexterm>PDF
<indexterm>change bars</indexterm></indexterm>
<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
<xref keyref="pdf2-creating-change-bars"/>.</p>
<p>Plug-ins that implemented custom FOP flagging by overriding the
<filepath>org.dita.pdf2.fop/xsl/fo/flagging_fop.xsl</filepath> stylesheet in prior versions will need to be
updated, as this file is no longer available in DITA-OT 3.6.
<xref href="https://github.com/dita-ot/dita-ot/issues/3511" format="html" scope="external">#3511</xref>,
<xref href="https://github.com/dita-ot/dita-ot/issues/3591" format="html" scope="external">#3591</xref>
</p>
</section>
<section id="no-dublin-core">
<title>Dublin Core metadata removed from HTML5</title>
<indexterm>Dublin Core metadata</indexterm>
<p>Up to version 3.5, DITA-OT included the
<xref keyref="dublin-core"/> in both XHTML and HTML5 output. DITA-OT 3.6 no longer generates Dublin Core
metadata in HTML5 output.</p>
<note type="tip">If necessary, the
<xref keyref="plugin-dublin-core"/> plug-in can be installed from the plug-in registry at
<xref keyref="site-plugin-registry"/> to add Dublin Core metadata to HTML5.</note>
<p>To install the plug-in, run the following command:</p>
<codeblock outputclass="syntax-bash"><cmdname>dita install</cmdname> org.dita.html5.dublin-core</codeblock>
</section>
<section id="3.6-inline-styles">
<title>Legacy style attributes moved to CSS</title>
<indexterm><xmlelement>line-through</xmlelement> styles</indexterm>
<indexterm><xmlelement>overline</xmlelement> styles</indexterm>
<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>
<li><line-through><xmlelement>line-through</xmlelement></line-through> and
<overline><xmlelement>overline</xmlelement></overline> elements</li>
<li>syntax diagrams</li>
<li>long quote citations</li>
<li>Boolean states</li>
</ul></p>
<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>
<note type="important">In publishing environments that do not use the default common CSS files, these styles may
need to be implemented in custom stylesheets.</note>
</section>
<section id="no-msgprefix">
<title>XSL variable <codeph>msgprefix</codeph> removed</title>
<p>The <codeph>msgprefix</codeph> variable (“DOTX”) has been deprecated since DITA-OT 2.3 and is now removed from
DITA-OT 3.6. For more information, see
<xref keyref="migrating-to-2.3"/>.</p>
</section>
</refbody>
</reference>

33
dita-ot-3.6/docsrc/topics/migration.dita Normal file
View file

@ -0,0 +1,33 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<reference id="ID">
<title>Migrating customizations</title>
<shortdesc>If you have XSL transformation overrides, plug-ins or other customizations written prior to DITA-OT
<keyword keyref="release"/>, you may need to make changes to ensure your overrides work properly with the latest
toolkit versions. </shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>upgrading
<indexterm>plug-ins</indexterm></indexterm>
<indexterm>upgrading
<index-see-also>migrating</index-see-also>
<index-see-also>installing</index-see-also></indexterm>
<indexterm>migrating</indexterm>
<indexterm>plug-ins
<indexterm>upgrading</indexterm></indexterm>
<indexterm>installing</indexterm>
</keywords>
</metadata>
</prolog>
<refbody>
<section>
<p>In some cases, you may be able to remove old code that is no longer needed. In other cases, you may need to
refactor your code to point to the modified extension points, templates or modes in recent toolkit versions.</p>
<p conkeyref="reusable-components/migration-recommendation"/>
<note>
<p conkeyref="conref-task/semver-info" conrefend="semver-plugins"/></note>
</section>
</refbody>
</reference>

27
dita-ot-3.6/docsrc/topics/migration.ditamap Normal file
View file

@ -0,0 +1,27 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<map>
<title>Migrating customizations</title>
<topicref keyref="migration">
<topicref keyref="migrating-to-3.6"/>
<topicref keyref="migrating-to-3.5"/>
<topicref keyref="migrating-to-3.4"/>
<topicref keyref="migrating-to-3.3"/>
<topicref keyref="migrating-to-3.2"/>
<topicref keyref="migrating-to-3.1"/>
<topicref keyref="migrating-to-3.0"/>
<topicref keyref="migrating-to-2.5"/>
<topicref keyref="migrating-to-2.4"/>
<topicref keyref="migrating-to-2.3"/>
<topicref keyref="migrating-to-2.2"/>
<topicref keyref="migrating-to-2.1"/>
<topicref keyref="migrating-to-2.0"/>
<topicref keyref="migrating-to-1.8"/>
<topicref keyref="migrating-to-1.7">
<topicref rev="1.7" keyref="flagging-migration"/>
</topicref>
<topicref keyref="migrating-to-1.6"/>
<topicref keyref="migrating-to-1.5.4"/>
</topicref>
</map>

62
dita-ot-3.6/docsrc/topics/other-errors.dita Normal file
View file

@ -0,0 +1,62 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<reference id="troubleshooting">
<title>Other error messages</title>
<shortdesc>In addition to error messages that DITA Open Toolkit generates, you might also encounter error messages
generated by Java or other tools.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>logging</indexterm>
<indexterm>Java
<indexterm>logging</indexterm></indexterm>
<indexterm>Java
<indexterm>out of memory</indexterm></indexterm>
<indexterm>Java
<indexterm>UnsupportedClassVersionError</indexterm></indexterm>
<indexterm>Java
<indexterm>tools.jar</indexterm></indexterm>
<indexterm>tools.jar</indexterm>
<indexterm>XSLT
<indexterm>errors</indexterm></indexterm>
<indexterm>preprocessing
<indexterm>XSLT</indexterm></indexterm>
<indexterm>debugging
<indexterm>generate-debug-attributes</indexterm></indexterm>
<indexterm>memory</indexterm>
</keywords>
</metadata>
</prolog>
<refbody>
<section id="out-of-memory-error">
<title>Out of Memory error</title>
<p>In some cases, you might receive a message stating the build has failed due to an <msgph>Out of Memory</msgph>
error. Try the following approaches to resolve the problem:</p>
<ol>
<li>Increase the memory available to Java.</li>
<li>Reduce memory consumption by setting the <option>generate-debug-attributes</option> option to
<codeph>false</codeph>. This option is set in the <filepath>lib/configuration.properties</filepath> 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>Set <codeph>dita.preprocess.reloadstylesheet</codeph> Ant property to <codeph>true</codeph>. This will allow
the XSLT processor to release memory when converting multiple files.</li>
<li>Run the transformation again.</li>
</ol>
</section>
<section id="unsupported-class-version-error">
<title>UnsupportedClassVersionError</title>
<p>If you receive a <codeph>java.lang.UnsupportedClassVersionError</codeph> error message with an
<codeph>Unsupported major.minor version</codeph> and a list of Java classes, make sure your system meets the
minimum Java requirements as listed in the <cite>Release Notes</cite> and installation instructions.</p>
</section>
<section id="tools-jar-error">
<title>Unable to locate tools.jar</title>
<p>If a Java Runtime Environment (JRE) is used when building output via Ant, the <msgph>Unable to locate
tools.jar</msgph> 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
<varname>JAVA_HOME</varname> environment variable to the location of the JDK will prevent this message from
appearing.</p>
</section>
</refbody>
</reference>

27
dita-ot-3.6/docsrc/topics/output-formats.dita Normal file
View file

@ -0,0 +1,27 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<concept id="availabletransforms">
<title>DITA-OT transformations (output formats)</title>
<titlealts>
<navtitle>Output formats</navtitle>
</titlealts>
<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
<xref keyref="site-plugin-registry"/>.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>output formats</indexterm>
<indexterm>transformations</indexterm>
<indexterm>DITA specification</indexterm>
<indexterm>plug-ins
<indexterm>default, list of</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<conbody>
<note type="tip">For information on how to install other formats, see
<xref keyref="adding-plugins"/>.</note>
</conbody>
</concept>

97
dita-ot-3.6/docsrc/topics/pdf-customization-approaches.dita Normal file
View file

@ -0,0 +1,97 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<concept id="pdf_customization_approaches">
<title>PDF customization approaches</title>
<titlealts>
<navtitle>Customization approaches</navtitle>
</titlealts>
<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.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>PDF
<indexterm>customizing, best practices</indexterm></indexterm>
<indexterm>upgrading
<indexterm>default plug-ins</indexterm></indexterm>
<indexterm>upgrading
<indexterm>PDF</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<conbody>
<note>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.</note>
<section id="why_not_edit_default_files">
<title>Why not edit default files?</title>
<p>When first experimenting with PDF customization, novice users are often tempted to simply edit the default
<filepath>org.dita.pdf2</filepath> files in place to see what happens.</p>
<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>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>
<note type="warning">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.</note>
</section>
<section id="the_customization_folder">
<title>Using the <filepath>Customization</filepath> folder</title>
<indexterm>deprecated features
<indexterm><filepath>Customization</filepath> folder</indexterm></indexterm>
<indexterm>Customization directory</indexterm>
<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>Files in the <filepath>org.dita.pdf2/Customization</filepath> 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>
<note type="important">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 <filepath>Customization</filepath> folder
is located within the <filepath>org.dita.pdf2</filepath> plug-in’s parent directory, users must be take care to
preserve the contents of this folder when upgrading to new toolkit versions.</note>
<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>
<note type="tip">Users who have used the <filepath>Customization</filepath> 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 <filepath>Customization</filepath> folder to a new subfolder in the
<filepath>plugins</filepath> folder and creating the necessary <filepath>plugin.xml</filepath> file and an Ant
script to define the transformation type as described in the following example.</note>
</section>
<section id="external_customization_directories">
<title>Specifying an external customization directory</title>
<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
<parmname>customization.dir</parmname> parameter.</p>
<p>This method is preferable to the use of the <filepath>org.dita.pdf2/Customization</filepath> 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>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>
<note type="tip">Users who specify external customization directories via <parmname>customization.dir</parmname>
are encouraged to create a custom PDF plug-in if possible.</note>
</section>
<section id="plug_ins_and_customization_folders">
<title>Combining custom plug-ins &amp; customization directories</title>
<p>A common custom plug-in may be used to store base overrides that are applicable to all company publications,
and the <parmname>customization.dir</parmname> parameter can be passed at build time to override individual
settings as necessary for a given project or publication.</p>
<p>In this case, any settings in the customization directory will take precedence over their counterparts in the
custom plug-in or default <filepath>org.dita.pdf2</filepath> plug-in.</p>
<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>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>
<note type="tip">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.</note>
</section>
</conbody>
</concept>

139
dita-ot-3.6/docsrc/topics/pdf-customization-example.dita Normal file
View file

@ -0,0 +1,139 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<task id="dita2pdf-customization" xml:lang="en">
<title>Example: Creating a simple PDF plug-in</title>
<titlealts>
<navtitle>Simple PDF plug-in</navtitle>
</titlealts>
<shortdesc>This scenario walks through the process of creating a very simple plug-in
(<codeph>com.example.print-pdf</codeph>) that creates a new transformation type: <option
>print-pdf</option>. </shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm><xmlelement>figure</xmlelement></indexterm>
<indexterm>PDF
<indexterm>plug-in</indexterm></indexterm>
<indexterm>integrator.xml</indexterm>
<indexterm>catalog
<indexterm>example</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<taskbody>
<context>
<p>The <option>print-pdf</option> transformation has the following characteristics:</p>
<ul>
<li>Uses A4 paper </li>
<li>Renders figures with a title at the top and a description at the bottom</li>
<li>Use em dashes as the symbols for unordered lists</li>
</ul>
</context>
<steps>
<step>
<cmd>In the <filepath>plugins</filepath> directory, create a directory named
<filepath>com.example.print-pdf</filepath>.</cmd>
</step>
<step>
<cmd>In the new <filepath>com.example.print-pdf</filepath> directory, create a plug-in configuration file
(<filepath>plugin.xml</filepath>) that declares the new <option>print-pdf</option> transformation and its
dependencies.</cmd>
<info>
<fig>
<title><filepath>plugin.xml</filepath> file</title>
<codeblock outputclass="language-xml normalize-space show-line-numbers show-whitespace"><coderef
href="../samples/plugins/com.example.print-pdf/plugin.xml"
/></codeblock>
</fig>
</info>
</step>
<step>
<cmd>Add an Ant script (<filepath>integrator.xml</filepath>) to define the transformation type.</cmd>
<info>
<fig>
<title><filepath>integrator.xml</filepath> file</title>
<codeblock outputclass="language-xml normalize-space show-line-numbers show-whitespace"><coderef
href="../samples/plugins/com.example.print-pdf/integrator.xml"
/></codeblock>
</fig></info>
</step>
<step>
<cmd>In the new plug-in directory, add a <filepath>cfg/catalog.xml</filepath> file that specifies the custom
XSLT style sheets.</cmd>
<stepxmp>
<fig>
<title><filepath>cfg/catalog.xml</filepath> file</title>
<codeblock outputclass="language-xml normalize-space show-line-numbers show-whitespace"><coderef
href="../samples/plugins/com.example.print-pdf/cfg/catalog.xml"
/></codeblock>
</fig>
</stepxmp>
</step>
<step>
<cmd>Create the <filepath>cfg/fo/attrs/custom.xsl</filepath> file, and add attribute and variable overrides to
it.</cmd>
<stepxmp>For example, add the following variables to change the page size to A4.<fig>
<title><filepath>cfg/fo/attrs/custom.xsl</filepath> file</title>
<codeblock outputclass="language-xml normalize-space show-line-numbers show-whitespace"><coderef
href="../samples/plugins/com.example.print-pdf/cfg/fo/attrs/custom.xsl"
/></codeblock>
</fig></stepxmp>
</step>
<step>
<cmd>Create the <filepath>cfg/fo/xsl/custom.xsl</filepath> file, and add XSLT overrides to it.</cmd>
<stepxmp>For example, the following code changes the rendering of <xmlelement>figure</xmlelement> elements.<fig>
<title><filepath>cfg/fo/xsl/custom.xsl</filepath> file</title>
<codeblock outputclass="language-xml normalize-space show-line-numbers show-whitespace"><coderef
href="../samples/plugins/com.example.print-pdf/cfg/fo/xsl/custom.xsl"
/></codeblock>
</fig></stepxmp>
</step>
<step>
<cmd>Create an English-language variable-definition file (<filepath>cfg/common/vars/en.xml</filepath>) and make
any necessary modifications to it.</cmd>
<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.<fig>
<title><filepath>cfg/common/vars/en.xml</filepath> file</title>
<codeblock outputclass="language-xml normalize-space show-line-numbers show-whitespace"><coderef
href="../samples/plugins/com.example.print-pdf/cfg/common/vars/en.xml"
/></codeblock>
</fig></stepxmp>
</step>
</steps>
<result>
<note type="tip">The files for this sample plug-in are included in the DITA-OT installation directory under
<filepath>docsrc/samples/plugins/com.example.print-pdf/</filepath> and on
<xref
href="https://github.com/dita-ot/docs/tree/develop/samples/plugins/com.example.print-pdf"
format="html"
scope="external"
>GitHub</xref>.</note>
<p>The plug-in directory has the following layout and files:</p>
<codeblock>com.example.print-pdf
├── cfg
│   ├── catalog.xml
│   ├── common
│   │   └── vars
│   │   └── en.xml
│   └── fo
│   ├── attrs
│   │   └── custom.xsl
│   └── xsl
│   └── custom.xsl
├── integrator.xml
└── plugin.xml</codeblock>
</result>
<postreq>
<ol>
<li>Run <filepath conkeyref="conref-task/dita-cmd"/>
<parmname>--install</parmname> to install the plug-in and make the <option>print-pdf</option> transformation
available.</li>
<li>Build output with the new transformation type to verify that the plug-in works as intended.
<codeblock><filepath conkeyref="conref-task/dita-cmd"/> <parmname>--input</parmname>=<varname
>my.ditamap</varname> <parmname>--format</parmname>=<option>print-pdf</option></codeblock>
</li>
</ol>
</postreq>
</taskbody>
</task>

36
dita-ot-3.6/docsrc/topics/pdf-customization-plugin-types.dita Normal file
View file

@ -0,0 +1,36 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<concept id="types-pdf-customization-plugins">
<title>Types of custom PDF plug-ins</title>
<titlealts>
<navtitle>Types of PDF plug-ins</navtitle>
</titlealts>
<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.</shortdesc>
<prolog>
<metadata>
<keywords/>
</metadata>
</prolog>
<conbody>
<section>
<title>Plug-in that only provides DITA-OT parameters</title>
<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
<xref keyref="plugin-set-parameters"/>.</p>
</section>
<section>
<title>Plug-in that overrides the base PDF transformation</title>
<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>
<li>Generated text strings</li>
<li>XSL templates</li>
<li>XSL-FO attribute sets</li>
</ul>
</section>
</conbody>
</concept>

19
dita-ot-3.6/docsrc/topics/pdf-customization-plugins.dita Normal file
View file

@ -0,0 +1,19 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<task id="custom-pdf-plugins">
<title>Custom PDF plug-ins</title>
<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.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>transformations
<indexterm>PDF</indexterm></indexterm>
<indexterm>PDF
<indexterm>custom plug-in</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
</task>

77
dita-ot-3.6/docsrc/topics/pdf-customization-resources.dita Normal file
View file

@ -0,0 +1,77 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<reference id="ID">
<title>Resources for custom PDF plug-ins</title>
<titlealts>
<navtitle>PDF plug-in resources</navtitle>
</titlealts>
<shortdesc>There are several external resources that can help you generate and refine custom PDF plug-ins for DITA
Open Toolkit.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>RenderX
<indexterm>plugin generator</indexterm></indexterm>
<indexterm>Antenna House
<indexterm>plugin generator</indexterm></indexterm>
<indexterm>Apache FOP
<indexterm>plugin generator</indexterm></indexterm>
<indexterm>Jarno Elovirta</indexterm>
<indexterm>PDF
<indexterm>plugin generator</indexterm></indexterm>
<indexterm>fonts
<indexterm>PDF plugin generator</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<refbody>
<section id="pdf-plugin-generator">
<title>PDF Plugin Generator</title>
<p>This online tool, developed and maintained by Jarno Elovirta, enables you to generate a PDF customization
plug-in automatically.</p>
<p>The application at
<xref
href="http://dita-generator.elovirta.com/"
format="html"
scope="external"
>dita-generator.elovirta.com</xref> 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>
<li>Define the target environment, selecting from the most current and two previous versions of DITA-OT</li>
<li>Select the XSL formatting engine (FOP, Antenna House Formatter, or RenderX XEP)</li>
<li>Specify page size, columns, and margins</li>
<li>Select from (limited) options for headers and footers</li>
<li>Specify layout options for chapters</li>
<li>Select formatting for the following publication components:
<ul>
<li>Normal text</li>
<li>Headings (levels one through four)</li>
<li>Titles for sections and examples</li>
<li>Tables and figures</li>
<li>Notes and examples</li>
<li>Lists (unordered, ordered, and definition)</li>
<li>Code blocks and pre-formatted text</li>
<li>Inline elements such as links and trademarks</li>
</ul><draft-comment author="Kristen Eberlein" time="13 February 2016">
<p>Given the technical level of our audience here, should we list DITA elements rather than the generic
categories?</p>
</draft-comment>
<p>For each component, you can specify: </p>
<ul>
<li>Font family, size, weight, and style</li>
<li>Color and background color</li>
<li>Alignment, indentation, spacing, and padding</li>
</ul></li>
</ul>
<note type="tip">The PDF Plugin Generator should be your first stop as you start developing a brand-new PDF
customization plug-in.</note>
</section>
<section conkeyref="reusable-components/dita-for-print"/>
<section conkeyref="reusable-components/dita-for-practitioners"/>
</refbody>
</reference>

37
dita-ot-3.6/docsrc/topics/pdf-customization.dita Normal file
View file

@ -0,0 +1,37 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<concept id="customizing-pdf-output">
<title>Customizing PDF output</title>
<titlealts>
<navtitle>Customizing PDF</navtitle>
</titlealts>
<shortdesc>You can <ph id="shortdesc-ph">adjust various aspects of PDF output by changing parameter settings</ph>. For
more complex customizations, you can create custom DITA-OT plug-ins.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>transformations
<indexterm>PDF</indexterm></indexterm>
<indexterm>PDF
<indexterm>customizing</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<conbody>
<p>For example:</p>
<ul>
<li>To print the file names of the graphics underneath figures, set <parmname>args.artlbl</parmname> to
<option>yes.</option></li>
<li>To disable the subsection links on the first page of each chapter, set
<parmname>args.chapter.layout</parmname> to <option>BASIC</option>.</li>
<li>To change the name of the PDF file to something other than the input map name, set
<parmname>outputFile.base</parmname> to the desired file name (without the <filepath>.pdf</filepath>
extension).</li>
</ul>
<note>For the full list of settings for PDF output, see
<xref keyref="parameters-pdf"/>.</note>
</conbody>
</concept>

22
dita-ot-3.6/docsrc/topics/pdf-customization.ditamap Normal file
View file

@ -0,0 +1,22 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<map>
<title>Customizing PDF output</title>
<topicref keyref="pdf-customization-approaches"/>
<topicref keyref="pdf2-creating-change-bars"/>
<reltable>
<title>Bi-directional links</title>
<relrow>
<relcell>
<topicref keyref="pdf-customization"/>
<topicref keyref="pdf-customization-approaches"/>
<topicref keyref="plugin-coding-conventions"/>
</relcell>
<relcell>
<topicref keyref="pdf-customization-plugins"/>
</relcell>
</relrow>
</reltable>
</map>

114
dita-ot-3.6/docsrc/topics/pdf-plugin-structure.dita Normal file
View file

@ -0,0 +1,114 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<concept id="pdf-plugin-structure">
<title>PDF plug-in structure</title>
<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.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>languages
<indexterm>adding support for</indexterm></indexterm>
<indexterm>I18N
<indexterm>plug-in</indexterm></indexterm>
<indexterm>PDF
<indexterm>plug-in</indexterm></indexterm>
<indexterm>font-mappings.xml</indexterm>
<indexterm>fonts
<indexterm>PDF</indexterm></indexterm>
<indexterm>PDF
<indexterm>fonts</indexterm></indexterm>
<indexterm>index
<indexterm>PDF</indexterm></indexterm>
<indexterm>Customization directory</indexterm>
</keywords>
</metadata>
</prolog>
<conbody>
<note>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.</note>
<p>The original Idiom plug-in used its own extension mechanism to provide overrides to the PDF transformation. With
this approach, a dedicated <filepath>Customization</filepath> folder within the plug-in was used as a
customization layer to store files that override the default behavior.</p>
<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>
<fig>
<title>Default <filepath>Customization</filepath> folder content</title>
<codeblock>.
├── build.properties.orig
├── catalog.xml.orig
└── fo/
├── attrs/
│ └── custom.xsl.orig
└── xsl/
└── custom.xsl.orig</codeblock>
</fig>
<p>To begin creating a new custom plug-in, you can copy the contents of the customization layer template in
<filepath>plugins/org.dita.pdf2/Customization</filepath> to a new folder that will serve as your new custom
plug-in folder, such as <filepath>plugins/com.company.pdf</filepath>.</p>
<p>To mimic the hierarchy of the default PDF plug-in, you may want to add a <filepath>cfg/</filepath> subfolder and
move the contents of the <filepath>fo/</filepath> folder to <filepath>cfg/fo/</filepath>.</p>
<p>DITA-OT provides template files that you can start with throughout the <filepath>Customization</filepath>
directory structure. These files end in the suffix <codeph>.orig</codeph> (for example,
<filepath>catalog.xml.orig</filepath>). To enable these files, remove the <codeph>.orig</codeph> suffix from the
copies in your new custom plug-in folder. (For example, rename <filepath>catalog.xml.orig</filepath> to
<filepath>catalog.xml</filepath>).</p>
<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
<filepath>layout-masters.xsl</filepath>, or the <filepath>font-mappings.xml</filepath> file that tells your PDF
renderer which fonts to use and where to find them.</p>
<note type="important"> 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
<xref keyref="plugin-coding-conventions"/>.</note>
<p>Things you can currently override include:</p>
<ul>
<li>Custom XSL via <filepath>xsl/custom.xsl</filepath> and <filepath>attrs/custom.xsl</filepath></li>
<li>Layout overrides via <filepath>layout-masters.xsl</filepath></li>
<li>Font overrides via <filepath>font-mappings.xml</filepath></li>
<li>Per-locale variable overrides via <filepath>common/vars/[language].xml</filepath></li>
<li>I18N configuration via <filepath>i18n/[language].xml</filepath></li>
<li>Index configuration via <filepath>index/[language].xml</filepath></li>
</ul>
<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
<filepath>catalog.xml</filepath> file.</p>
<p>It should look like this:</p>
<codeblock
outputclass="language-xml"
>&lt;!--uri name="cfg:fo/attrs/custom.xsl" uri="fo/attrs/custom.xsl"/--&gt;</codeblock>
<p>Remove the comment markers <codeph>!--</codeph> and <codeph>--</codeph> to enable the change:</p>
<codeblock
outputclass="language-xml"
>&lt;uri name="cfg:fo/attrs/custom.xsl" uri="fo/attrs/custom.xsl"/&gt;</codeblock>
<p>Your customization should now be enabled as part of the publishing process.</p>
<fig>
<title>Sample custom plug-in structure</title>
<codeblock>.
├── 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</codeblock>
</fig>
<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 <filepath>org.dita.pdf2/cfg/fo/attrs</filepath> and
<filepath>org.dita.pdf2/xsl/fo</filepath>.</p>
<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>
</conbody>
</concept>

28
dita-ot-3.6/docsrc/topics/pdf-plugin-structure_common-artwork.dita Normal file
View file

@ -0,0 +1,28 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<topic id="custom_artwork_the_common_artwork_folder">
<title>Custom artwork</title>
<shortdesc>The <filepath>common/artwork</filepath> folder houses custom artwork files that override the standard icons
in <filepath>org.dita.pdf2/cfg/common/artwork</filepath>.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm><xmlelement>note</xmlelement></indexterm>
<indexterm><xmlatt>type</xmlatt></indexterm>
<indexterm>locale</indexterm>
</keywords>
</metadata>
</prolog>
<body>
<p>These files are used to graphically identify different types of DITA <xmlelement>note</xmlelement> element.</p>
<p>The mapping between <xmlelement>note</xmlelement> type and graphic is contained in the common variables file
<filepath>org.dita.pdf2/cfg/common/vars/commonvariables.xml</filepath>.</p>
<p>The variables that control <xmlelement>note</xmlelement> graphics all follow the form</p>
<codeblock outputclass="language-xml">&lt;variable id="<varname>{type}</varname> Note Image Path"&gt; <varname
>{path to image file}</varname> &lt;/variable&gt;</codeblock>
<p>where <varname>{type}</varname> contains a possible value for the <xmlelement>note</xmlelement>
<xmlatt>type</xmlatt> attribute and <varname>{path to image file}</varname> is the path to the note icon
image.</p>
</body>
</topic>

40
dita-ot-3.6/docsrc/topics/pdf-plugin-structure_common-index.dita Normal file
View file

@ -0,0 +1,40 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<topic id="index_configuration_the_common_index_folder">
<title>Index configuration</title>
<shortdesc>The <filepath>common/index</filepath> folder houses custom index definition files that override the
standard definitions in <filepath>org.dita.pdf2/cfg/common/index</filepath>.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm><xmlelement>index.group</xmlelement></indexterm>
<indexterm><xmlelement>char.set</xmlelement></indexterm>
<indexterm>languages
<indexterm>ISO 639-1</indexterm></indexterm>
<indexterm>ISO 639-1</indexterm>
<indexterm>Portuguese</indexterm>
<indexterm>index
<indexterm>PDF</indexterm></indexterm>
<indexterm>catalog
<indexterm><filepath>catalog.xml</filepath></indexterm></indexterm>
<indexterm>catalog
<indexterm>index configuration</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<body>
<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, <filepath>pt.xml</filepath> for Portuguese). If necessary, locale-specific customizations
can be provided by adding a region designator to the file name (for example, <filepath>pt_BR.xml</filepath> for
Brazilian Portuguese).</p>
<p>The index files consist of <xmlelement>index.group</xmlelement> 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 <xmlelement>char.set</xmlelement> entries they contain are also listed in sort order (uppercase
before lowercase).</p>
<p>The best way to start editing a custom index file is by making a copy of the original from
<filepath>org.dita.pdf2/cfg/common/index</filepath> and making changes as desired.</p>
<p>In order to apply a custom index definition to your publishing outputs, edit <filepath>catalog.xml</filepath> and
uncomment the appropriate entry in the “Index configuration override entries” section.</p>
</body>
</topic>

44
dita-ot-3.6/docsrc/topics/pdf-plugin-structure_common-vars.dita Normal file
View file

@ -0,0 +1,44 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<topic id="variable_overrides_the_common_vars_folder">
<title>Variable overrides</title>
<shortdesc>The <filepath>common/vars</filepath> folder houses custom variable definitions that override the standard
definitions in <filepath>org.dita.pdf2/cfg/common/vars</filepath>. </shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm><xmlelement>variable</xmlelement></indexterm>
<indexterm><xmlelement>param</xmlelement></indexterm>
<indexterm><xmlatt>id</xmlatt>
<indexterm>variables, overriding</indexterm></indexterm>
<indexterm>languages
<indexterm>adding support for</indexterm></indexterm>
<indexterm>languages
<indexterm>ISO 639-1</indexterm></indexterm>
<indexterm>ISO 639-1</indexterm>
</keywords>
</metadata>
</prolog>
<body>
<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>Variable files contain a set of <xmlelement>variable</xmlelement> elements, identified by their
<xmlatt>id</xmlatt> 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>Some variables contain <xmlelement>param</xmlelement> 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
<xmlelement>variable</xmlelement> content as needed.</p>
<p>The best way to start editing a custom variables file is by making a copy of the original from
<filepath>org.dita.pdf2/cfg/common/vars</filepath> 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>Note that unchanged <xmlelement>variable</xmlelement> elements can be omitted: the custom variables file need
only include those <xmlelement>variable</xmlelement> elements which you have modified. Variables not found in the
custom file will are taken from the standard variable files.</p>
<p>Applying a custom variable does not require modifying the <filepath>catalog.xml</filepath> file. The publishing
process will automatically use any custom variables definitions in place of the original ones.</p>
</body>
</topic>

35
dita-ot-3.6/docsrc/topics/pdf-plugin-structure_fo-attrs.dita Normal file
View file

@ -0,0 +1,35 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<topic id="custom_attributes_the_fo_attrs_folder">
<title>Custom attributes</title>
<shortdesc>The <filepath>fo/attrs</filepath> folder houses custom attribute configuration files that override the
standard attributes in <filepath>org.dita.pdf2/cfg/fo/attrs</filepath>.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>fonts
<indexterm>PDF</indexterm></indexterm>
<indexterm>PDF
<indexterm>fonts</indexterm>
<indexterm>index</indexterm>
<indexterm>tables</indexterm></indexterm>
<indexterm>index
<indexterm>PDF</indexterm></indexterm>
<indexterm>tables
<indexterm>tables.attr.xsl</indexterm></indexterm>
<indexterm>tables
<indexterm>PDF</indexterm></indexterm>
<indexterm>index-attr.xsl</indexterm>
<indexterm>tables-attr.xsl</indexterm>
</keywords>
</metadata>
</prolog>
<body>
<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
<filepath>index-attr.xsl</filepath>, table-related definitions in <filepath>tables-attr.xsl</filepath>, etc.</p>
<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>
</body>
</topic>

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