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

27
dita-ot-3.6/docsrc/reference/architecture.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="ditaotarch">
<title>DITA Open Toolkit Architecture</title>
<titlealts>
<navtitle>DITA-OT architecture</navtitle>
</titlealts>
<shortdesc>DITA Open Toolkit is an open-source implementation of the OASIS specification for the Darwin Information
Typing Architecture. The toolkit uses Ant, XSLT, and Java to transform DITA content (maps and topics) into different
deliverable formats.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>authoring formats
<indexterm>DITA</indexterm></indexterm>
<indexterm>OASIS</indexterm>
<indexterm>architecture</indexterm>
<indexterm>Ant</indexterm>
<indexterm>Java
<indexterm>architecture</indexterm></indexterm>
<indexterm>XSLT
<indexterm>DITA-OT architecture</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
</concept>

13
dita-ot-3.6/docsrc/reference/books.dita Normal file
View file

@ -0,0 +1,13 @@
<?xml version="1.0" encoding="UTF-8"?>
<?xml-model href="urn:oasis:names:tc:dita:rng:topic.rng" schematypens="http://relaxng.org/ns/structure/1.0"?>
<?xml-model href="urn:oasis:names:tc:dita:rng:topic.rng" schematypens="http://purl.oclc.org/dsdl/schematron"?>
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<topic id="books">
<title>Books</title>
<shortdesc>Several DITA-related publications include information on configuring and customizing DITA Open Toolkit
with detailed examples on creating custom plug-ins for PDF output.</shortdesc>
<body>
<section conkeyref="reusable-components/dita-for-print"/>
<section conkeyref="reusable-components/dita-for-practitioners"/>
</body>
</topic>

41
dita-ot-3.6/docsrc/reference/common-html-processing.dita Normal file
View file

@ -0,0 +1,41 @@
<?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="common-html-processing">
<title>Common HTML-based processing</title>
<shortdesc>After the pre-processing operation runs, HTML-based builds each run a common series of Ant targets to
generate HTML file. Navigation may be created before or after this set of common routines.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm><xmlatt>chunk</xmlatt>
<indexterm>HTML-based processing</indexterm></indexterm>
<indexterm>DITAVAL
<indexterm>HTML-based formats</indexterm></indexterm>
<indexterm>HTML
<indexterm>common processing</indexterm></indexterm>
<indexterm>CSS
<indexterm>HTML transforms</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<conbody>
<p>After the pre-processing is completed, the following targets are run for all of the HTML-based builds:</p>
<p>
<ul>
<li>If the <parmname>args.css</parmname> parameter is passed to the build to add a CSS file, the
<codeph>copy-css</codeph> target copies the CSS file from its source location to the relative location in
the output directory.</li>
<li>If a DITAVAL file is used, the <codeph>copy-revflag</codeph> target copies the default start- and
end-revision flags into the output directory.</li>
<li>The DITA topics are converted to HTML files. Unless the <xmlatt>chunk</xmlatt> attribute was specified, each
DITA topic in the temporary directory now corresponds to one HTML file. The
<codeph>dita.inner.topics.xhtml</codeph> target is used to process documents that are in the map directory
(or subdirectories of the map directory). The <codeph>dita.outer.topics.xhtml</codeph> target is used to
process documents that are outside of the scope of the map, and thus might end up outside of the designated
output directory. Various DITA-OT parameters control how documents processed by the
<codeph>dita.outer.topics.xhtml</codeph> target are handled.</li>
</ul>
</p>
</conbody>
</concept>

19
dita-ot-3.6/docsrc/reference/dita-spec-support.dita Normal file
View file

@ -0,0 +1,19 @@
<?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-spec-support">
<title>DITA specification support</title>
<shortdesc>DITA Open Toolkit <keyword keyref="release"/> supports all versions of the OASIS DITA specification,
including 1.0, 1.1, 1.2, and 1.3.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>authoring formats
<indexterm>DITA</indexterm></indexterm>
<indexterm>DITA 1.0</indexterm>
<indexterm>DITA 1.1</indexterm>
</keywords>
</metadata>
</prolog>
<conbody/>
</concept>

61
dita-ot-3.6/docsrc/reference/dita-v1-2-support.dita Normal file
View file

@ -0,0 +1,61 @@
<?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="dita1.2specification">
<title>DITA 1.2 support</title>
<shortdesc>DITA Open Toolkit <keyword keyref="release"/> supports the DITA 1.2 specification. While 1.2 is no longer
the latest version of DITA, the grammar files (DTD and XML Schema) are still included with DITA-OT and content
explicitly created for 1.2 continues to work as intended.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm><xmlelement>abbreviated-form</xmlelement></indexterm>
<indexterm><xmlatt>keyref</xmlatt></indexterm>
<indexterm><xmlatt>processing-role</xmlatt></indexterm>
<indexterm><xmlatt>conref</xmlatt>
<indexterm>support</indexterm></indexterm>
<indexterm>filters
<indexterm>subject scheme</indexterm></indexterm>
<indexterm>DITA
<indexterm>specializations</indexterm></indexterm>
<indexterm>DTD</indexterm>
<indexterm>schema
<indexterm>DITA 1.2</indexterm></indexterm>
<indexterm>grammar files</indexterm>
<indexterm>DITA 1.2</indexterm>
<indexterm>SCORM</indexterm>
</keywords>
</metadata>
</prolog>
<conbody>
<p>Highlights of DITA 1.2 support in the toolkit include:
<ul>
<li>Processing support for all new elements and attributes</li>
<li>Link redirection and text replacement using <xmlatt>keyref</xmlatt></li>
<li>New <xmlatt>processing-role</xmlatt> attribute in maps to allow references to topics that will not produce
output artifacts</li>
<li>New content reference extensions, including the ability to reference a range of elements, to push content
into another topic, and to use keys for resolving a <xmlatt>conref</xmlatt> attribute.</li>
<li>The ability to filter content with controlled values and taxonomies using Subject Scheme Maps</li>
<li>Processing support for both default versions of task (original, limited task, and the general task with
fewer constraints on element order)</li>
<li>Acronym and abbreviation support with the new <xmlelement>abbreviated-form</xmlelement> element</li>
<li>New link grouping abilities available with headers in relationship tables</li>
<li>OASIS Subcommittee specializations from the learning and machine industry domains (note that the core
toolkit contains only basic processing support for these, but can be extended to produce related artifacts
such as SCORM modules)</li>
</ul></p>
<p>To find detailed information about any of these features, see the specification documents at OASIS. The DITA
Adoption Technical Committee has also produced several papers to describe individual new features. In general, the
white papers are geared more towards DITA users and authors, while the specification is geared more towards tool
implementors, though both may be useful for either audience. The DITA Adoption papers can be found from that
committee’s main web page.</p>
</conbody>
<related-links>
<link keyref="dita12-xhtml"/>
<link keyref="dita12-pdf"/>
<link keyref="dita12-source"/>
<link keyref="dita-tc"/>
<link keyref="dita-adoption-tc"/>
</related-links>
</concept>

87
dita-ot-3.6/docsrc/reference/dita-v1-3-support.dita Normal file
View file

@ -0,0 +1,87 @@
<?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-13-spec-support">
<title>DITA 1.3 support</title>
<shortdesc><ph id="shortdesc-ph">DITA Open Toolkit <keyword keyref="release"/> provides processing support for the
OASIS DITA 1.3 specification. Initial preview support for this specification was added in version 2.0 of the
toolkit; version 2.2 extended this foundation to support key scopes and branch filtering along with additional
DITA 1.3 features.</ph></shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm><xmlelement>ditavalref</xmlelement></indexterm>
<indexterm><xmlelement>xmlelement</xmlelement></indexterm>
<indexterm><xmlelement>xmlatt</xmlelement></indexterm>
<indexterm><xmlelement>line-through</xmlelement></indexterm>
<indexterm><xmlelement>overline</xmlelement></indexterm>
<indexterm><xmlelement>object</xmlelement></indexterm>
<indexterm><xmlelement>div</xmlelement>
<indexterm>support</indexterm></indexterm>
<indexterm><xmlatt>keyscope</xmlatt></indexterm>
<indexterm><xmlatt>deliveryTarget</xmlatt></indexterm>
<indexterm><xmlatt>orient</xmlatt></indexterm>
<indexterm><xmlatt>keyref</xmlatt></indexterm>
<indexterm><xmlatt>cascade</xmlatt></indexterm>
<indexterm>profiling</indexterm>
<indexterm>filters
<indexterm>support</indexterm></indexterm>
<indexterm>branch filters</indexterm>
<indexterm>DTD</indexterm>
<indexterm>schema
<indexterm>DITA 1.3</indexterm></indexterm>
<indexterm>grammar files</indexterm>
<indexterm>DITA 1.3
<indexterm>specification support</indexterm></indexterm>
<indexterm>catalog
<indexterm>grammar file resolution</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<conbody>
<p id="p">Because DITA 1.3 is fully backwards compatible with previous DITA DTDs and schemas, DITA-OT provides the
1.3 materials as the default grammar files for processing. The XML Catalog resolution maps any references for
unversioned DITA document types to the 1.3 versions. All processing ordinarily dependent on the 1.0, 1.1, or 1.2
definitions continues to work as usual, and any documents that make use of the newer DITA 1.3 elements or
attributes will be supported with specific new processing.</p>
<section>
<title>Major features of DITA 1.3</title>
<p>The following DITA 1.3 features are supported in DITA Open Toolkit.</p>
<ul>
<li>
<xref keyref="dita13-spec-keyscopes">Scoped keys</xref> supported using DITA 1.3 <xmlatt>keyscope</xmlatt>
attribute</li>
<li>
<xref keyref="dita13-spec-branch-filter">Branch filtering</xref> using <xmlelement>ditavalref</xmlelement>
elements in a map</li>
<li>Support formatting based on new XML Mention elements, such as adding angle brackets around elements tagged
with <xmlelement>xmlelement</xmlelement> and adding <codeph>@</codeph> before attributes tagged with
<xmlelement>xmlatt</xmlelement></li>
<li>New highlighting elements <xmlelement>line-through</xmlelement> and <xmlelement>overline</xmlelement></li>
<li>Support for profiling based on <xmlatt>deliveryTarget</xmlatt> attribute</li>
<li>Support for the new <xmlatt>orient</xmlatt> attribute for rotating tables</li>
<li>Profile (filter or flag) based on
<xref keyref="dita13-spec-profile-groups">groups within profiling attributes</xref></li>
<li><xmlatt>keyref</xmlatt> and related key referencing attributes supported on
<xmlelement>object</xmlelement></li>
<li>New in-topic link syntax using <codeph>.</codeph> in place of the topic ID: <codeph>#./figure</codeph></li>
<li>Support for additional new elements, such as the <xmlelement>div</xmlelement> element for grouping</li>
<li>Support <xmlatt>cascade</xmlatt> attribute in maps (processing defaults to the value <codeph>merge</codeph>,
which is the
<xref keyref="dita13-spec-metadata-cascade-example">default cascade operation</xref> described by the DITA
specification)</li>
</ul>
<note>For the latest status information on DITA 1.3-related features and fixes, see the
<xref keyref="dita13-issues"/> in the GitHub issues tracker.</note>
</section>
</conbody>
<related-links>
<link keyref="dita13-spec-all-inclusive"/>
<link keyref="dita13-spec-all-inclusive-pdf"/>
<link keyref="dita13-spec-source"/>
<link keyref="dita-tc"/>
<link keyref="dita-adoption-tc"/>
</related-links>
</concept>

108
dita-ot-3.6/docsrc/reference/dita-v2-0-support.dita Normal file
View file

@ -0,0 +1,108 @@
<?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>DITA 2.0 preview support</title>
<titlealts>
<navtitle>DITA 2.0 preview</navtitle>
</titlealts>
<shortdesc>DITA Open Toolkit <keyword keyref="release"/> provides a preview of features for the upcoming OASIS DITA
2.0 specification. This preliminary processing support is provided on the basis of the latest DRAFT versions of the
DITA 2.0 DTD and RELAX NG grammar files from OASIS (as of October 2020).</shortdesc>
<conbody>
<p id="grammar-files">DITA documents that reference the draft grammar files can be parsed, and where features
overlap with DITA 1.3, those features will work as expected.</p>
<section>
<title>DITA-OT 3.5</title>
<p>DITA-OT 3.5 provided an initial preview of DITA 2.0 features.</p>
<ul>
<li id="3453">
<p>
<ph id="include">The new <xmlelement>include</xmlelement> element can be used to reference text or XML
content from other files. In addition to the processing mandated by the specification, DITA-OT also
supports the character set definition and line range extraction options previously provided for
<xmlelement>coderef</xmlelement> elements (see
<xref keyref="extended-functionality"/>).</ph>
</p>
</li>
<li id="3462">
<p>
<ph id="specializations">The new <xmlatt>specializations</xmlatt> attribute, which replaces the DITA 1.x
<xmlatt>domains</xmlatt> attribute, can now be used as an alternative method of declaring specialized
attributes.</ph>
</p>
</li>
<li id="3463">
<p>
<ph id="outputclass">The <xmlatt>outputclass</xmlatt> attribute can now be specified as a flagging behavior
in DITAVAL files. This allows you to flag an element with a CSS class keyword that will be added to the
<xmlatt>class</xmlatt> attribute value in the generated HTML. Output classes allow you to pick up
pre-defined styles from existing web frameworks, and are more easily overridden with custom CSS files than
the inline <xmlatt>style</xmlatt> attributes generated by DITA 1.x flagging options such as
<xmlatt>color</xmlatt> and <xmlatt>backcolor</xmlatt>.</ph>
</p>
</li>
<li id="3464">
<p>
<ph id="simple-table-titles">Titles can now be specified on simple tables, and
<xmlelement>simpletable</xmlelement> entries now support row and column spanning attributes.</ph>
</p>
</li>
<li id="3483">
<p>
<ph id="topic-based-classes">Where DITA 1.x defined conflicting <xmlatt>class</xmlatt> values for
<xmlelement>linktext</xmlelement>, <xmlelement>shortdesc</xmlelement>, and
<xmlelement>searchtitle</xmlelement> in maps and topics, the new draft of DITA 2.0 uses the topic-based
<xmlatt>class</xmlatt> value in all cases. Processing is updated to recognize the updated value when
these elements are used in maps.</ph>
</p>
</li>
</ul>
</section>
<section>
<title>DITA-OT 3.6</title>
<p>DITA-OT 3.6 adds support for additional DITA 2.0 features.</p>
<ul id="added-in-3.6">
<!-- Added in DITA-OT 3.6 -->
<li>Where earlier DITA versions relied on the <xmlelement>object</xmlelement> to embed media in DITA source
files, DITA 2.0 provides new <xmlelement>audio</xmlelement> and <xmlelement>video</xmlelement> elements that
correspond to their HTML5 equivalents.</li>
<li>For HTML5 compatibility, the new emphasis domain adds support for the <xmlelement>strong</xmlelement> and
<xmlelement>em</xmlelement> elements in addition to the existing <xmlelement>b</xmlelement> and
<xmlelement>i</xmlelement> elements in the highlighting domain.</li>
<li>The troubleshooting domain has been updated with additional constructs that can be used to provide detailed
diagnostic information.</li>
<li>Several obsolete elements and attributes have been removed from DITA 2.0, including:
<ul>
<li><xmlelement>boolean</xmlelement></li>
<li><xmlelement>data-about</xmlelement></li>
<li><xmlelement>indextermref</xmlelement></li>
<li><xmlatt>alt</xmlatt> on <xmlelement>image</xmlelement></li>
<li><xmlatt>navtitle</xmlatt> on <xmlelement>topicref</xmlelement></li>
<li><xmlatt>query</xmlatt> on <xmlelement>topicref</xmlelement></li>
<li><xmlatt>refcols</xmlatt> on <xmlelement>simpletable</xmlelement></li>
<li><xmlatt>xtrc</xmlatt></li>
<li><xmlatt>xtrf</xmlatt></li>
</ul>
</li>
</ul>
<note id="more-to-come">Other new or revised features proposed for DITA 2.0 are not yet supported. Additional
features will be implemented in future versions of DITA-OT as the specification evolves.</note>
<note type="tip">For the latest status information on DITA 2.0-related features and fixes, see the
<xref keyref="dita20-issues"/> in the GitHub issues tracker.</note>
</section>
</conbody>
<related-links>
<!--
<link keyref="dita13-spec-all-inclusive"/>
<link keyref="dita13-spec-all-inclusive-pdf"/>
<link keyref="dita13-spec-source"/>
-->
<link keyref="dita-tc"/>
</related-links>
</concept>

132
dita-ot-3.6/docsrc/reference/docs-dita-features.dita Normal file
View file

@ -0,0 +1,132 @@
<?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>DITA features in the documentation</title>
<titlealts>
<navtitle>DITA features in docs</navtitle>
</titlealts>
<shortdesc>DITA Open Toolkit uses various recent DITA features in the project documentation.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm><xmlatt>audience</xmlatt></indexterm>
<indexterm><xmlatt>orient</xmlatt></indexterm>
<indexterm>profiling</indexterm>
<indexterm>branch filters</indexterm>
<indexterm>Antenna House
<indexterm>DITA XML mention domain</indexterm></indexterm>
<indexterm>DITA 1.3
<indexterm>XML mention domain</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<conbody>
<p>The
<xref href="https://github.com/dita-ot/docs" format="html" scope="external">source files</xref> for the DITA-OT
documentation include examples of the following DITA features (among others):</p>
<ul>
<li>subjectScheme classification for controlling available attributes</li>
<li>profiling and branch filtering (novice/expert content)</li>
<li>extending topics with conref push</li>
<li>keys and key references</li>
<li>XML mention domain</li>
</ul>
<section>
<title>Subject schemes </title>
<p>Various topics, sections and elements in the docs are profiled by audience:</p>
<p><codeblock outputclass="language-xml normalize-space show-line-numbers show-whitespace"><coderef
href="../resources/conref-task.dita#token=excerpt-variables,end-excerpt"
/></codeblock></p>
<p>An “audience” subject scheme controls the values that are available for the <xmlatt>audience</xmlatt>
attribute:</p>
<p><codeblock outputclass="language-xml normalize-space show-line-numbers show-whitespace"><coderef
href="../resources/subjectscheme.ditamap#token=excerpt-audience,end-excerpt"
/></codeblock></p>
<p>A dedicated subject scheme map defines several series of permissible values for <xmlatt>outputclass</xmlatt>
attributes, which apply styling to elements on the project website, enable
<xref keyref="extended-functionality">extended codeblock processing</xref> such as whitespace visualization and
line numbering in PDF output, or trigger
<xref keyref="html5-code-highlighting"/> via
<xref keyref="prismjs"/>.</p>
<p><codeblock outputclass="language-xml normalize-space show-line-numbers show-whitespace"><coderef
href="../resources/subjectscheme.ditamap#token=excerpt-outputclass,excerpt-audience"
/></codeblock></p>
</section>
<section>
<title>Branch filtering: re-using profiled content</title>
</section>
<section>
<p><cite>Installing DITA-OT</cite> pulls a subset of the build description from <cite>using the
<cmdname>dita</cmdname> command</cite>, filtered to display only content deemed suitable for novice users
under
<xref keyref="first-build-using-dita-command"/>:</p>
<p><codeblock outputclass="language-xml normalize-space show-line-numbers show-whitespace"><coderef
href="../topics/installing.ditamap#token=branch-filter,end-filtering"
/></codeblock></p>
<p>The same content appears later in
<xref keyref="build-using-dita-command"/> with additional information on arguments, options and examples.</p>
<p><codeblock outputclass="language-xml normalize-space show-line-numbers show-whitespace"><coderef
href="../topics/publishing.ditamap#token=branch-filter,end-filtering"
/></codeblock></p>
</section>
<section>
<title>Conref push</title>
</section>
<section>
<p>The docs build uses the conref push mechanism (with the <codeph>pushreplace</codeph>, <codeph>mark</codeph>,
and <codeph>pushafter</codeph>
<xref keyref="dita13-spec-conaction">conactions</xref>) to extend the parameter descriptions embedded in the
default plug-ins:</p>
<p><codeblock outputclass="language-xml normalize-space show-line-numbers show-whitespace"><coderef
href="../parameters/ant-parameters-details.dita#token=excerpt-csspath,end-excerpt"
/></codeblock></p>
<p>The pushed content appears in the output after the default description. (See
<xref keyref="parameters-base-html"/>.)</p>
<note type="tip">You could also use the same mechanism to extend the documentation with custom information that
applies only to your company’s toolkit distribution.</note>
</section>
<section>
<title>Keys and key references</title>
</section>
<section>
<p>The <codeph>key-definitions.ditamap</codeph> defines keys for version references, re-usable links, etc.</p>
<p>This key definition defines the maintenance release version:</p>
<p><codeblock outputclass="language-xml normalize-space"><coderef
href="../resources/key-definitions.ditamap#token=excerpt-version,end-excerpt"
/></codeblock></p>
<p>In topics, the keyword is used in place of hard-coded version references:</p>
<codeblock
outputclass="language-xml"
>&lt;title&gt;DITA Open Toolkit &lt;keyword keyref="maintenance-version"/&gt; Release Notes&lt;/title&gt;</codeblock>
</section>
<section>
<title>XML mention domain</title>
</section>
<section>
<p>The docs use the
<xref
format="html"
href="http://docs.oasis-open.org/dita/dita/v1.3/os/part3-all-inclusive/langRef/containers/xml-mention-domain.html#xml-mention-domain"
scope="external"
>XML mention domain</xref> to mark up XML elements and attributes:</p>
<codeblock outputclass="language-xml">&lt;li id="1777"&gt;
DITA 1.3: Initial support has been added for the &lt;xmlatt&gt;orient&lt;/xmlatt&gt;
attribute on &lt;xmlelement&gt;table&lt;/xmlelement&gt; elements. These changes allow
Antenna House Formatter to render tables in landscape mode when the
&lt;xmlatt&gt;orient&lt;/xmlatt&gt; attribute is set to &lt;option&gt;land&lt;/option&gt;. […]
&lt;/li&gt;</codeblock>
<p>When the toolkit generates output for the sample above:</p>
<ul>
<li>the XML element name is wrapped in angle brackets as <xmlelement>table</xmlelement>
</li>
<li>the attribute name is prefixed with an “at” sign as <xmlatt>orient</xmlatt></li>
</ul>
</section>
</conbody>
</concept>

75
dita-ot-3.6/docsrc/reference/eclipsehelp-processing.dita Normal file
View file

@ -0,0 +1,75 @@
<?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="xhtmleclipse">
<title>Eclipse help processing</title>
<shortdesc>The <option>eclipsehelp</option> transformation generates XHTML-based output and files that are needed to
create an Eclipse Help system plug-in. Once the normal XHTML process has run, the <codeph>dita.map.eclipse</codeph>
target is used to create a set of control files and navigation files.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>HTML
<indexterm>Eclipse Help</indexterm></indexterm>
<indexterm>dita.map.eclipse</indexterm>
<indexterm>Eclipse Help</indexterm>
<indexterm>targets
<indexterm>Eclipse Help</indexterm></indexterm>
<indexterm>index
<indexterm>Eclipse Help</indexterm></indexterm>
<indexterm>table of contents
<indexterm>Eclipse Help</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<conbody>
<section>
<p>Eclipse uses multiple files to control the plug-in behavior. Some of these control files are generated by the
build, while others might be created manually. The following Ant targets control the Eclipse help
processing:</p>
<p>
<dl>
<dlentry>
<dt><codeph>dita.map.eclipse.init</codeph></dt>
<dd>Sets up various default properties</dd>
</dlentry>
<dlentry>
<dt><codeph>dita.map.eclipse.toc</codeph></dt>
<dd>Creates the XML file that defines an Eclipse table of contents</dd>
</dlentry>
<dlentry>
<dt><codeph>dita.map.eclipse.index</codeph></dt>
<dd>Creates the sorted XML file that defines an Eclipse index</dd>
</dlentry>
<dlentry>
<dt><codeph>dita.map.eclipse.plugin</codeph></dt>
<dd>Creates the <filepath>plugin.xml</filepath> file that controls the behavior of an Eclipse plug-in</dd>
</dlentry>
<dlentry>
<dt><codeph>dita.map.eclipse.plugin.properties</codeph></dt>
<dd>Creates a Java properties file that sets properties for the plug-in, such as name and version
information</dd>
</dlentry>
<dlentry>
<dt><codeph>dita.map.eclipse.manifest.file</codeph></dt>
<dd>Creates a <filepath>MANIFEST.MF</filepath> file that contains additional information used by
Eclipse</dd>
</dlentry>
<dlentry>
<dt><codeph>copy-plugin-files</codeph></dt>
<dd>Checks for the presence of certain control files in the source directory, and copies those found to the
output directory</dd>
</dlentry>
<dlentry>
<dt><codeph>dita.map.eclipse.fragment.language.init</codeph></dt>
<dd>Works in conjunction with the <codeph>dita.map.eclipse.fragment.language.country.init</codeph> and
<codeph>dita.map.eclipse.fragment.error</codeph> targets to control Eclipse fragment files, which are
used for versions of a plug-in created for a new language or locale</dd>
</dlentry>
</dl>
</p>
<p>Several of the targets listed above have matching templates for processing content that is located outside of
the scope of the map directory, such as <codeph>dita.out.map.eclipse.toc</codeph>.</p>
</section>
</conbody>
</concept>

174
dita-ot-3.6/docsrc/reference/extended-functionality.dita Normal file
View file

@ -0,0 +1,174 @@
<?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="code-reference">
<title>Extended codeblock processing</title>
<titlealts>
<navtitle>Codeblock extensions</navtitle>
</titlealts>
<shortdesc>DITA-OT provides additional processing support beyond that which is mandated by the DITA specification.
These extensions can be used to define character encodings or line ranges for code references, normalize
indendation, add line numbers or display whitespace characters in code blocks.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm><xmlelement>coderef</xmlelement></indexterm>
<indexterm><xmlelement>codeblock</xmlelement></indexterm>
<indexterm><xmlatt>format</xmlatt></indexterm>
<indexterm><xmlatt>outputclass</xmlatt></indexterm>
<indexterm>encoding</indexterm>
<indexterm><msgnum>DOTJ052E</msgnum></indexterm>
<indexterm>character set</indexterm>
</keywords>
</metadata>
</prolog>
<refbody>
<section id="coderef-charset">
<title>Character set definition</title>
<p>For <xmlelement>coderef</xmlelement> elements, DITA-OT supports defining the code reference target file
encoding using the <xmlatt>format</xmlatt> attribute. The supported format is:</p>
<codeblock>format (";" space* "charset=" charset)?</codeblock>
<p>If a character set is not defined, the system default character set will be used. If the character set is not
recognized or supported, the <msgnum>DOTJ052E</msgnum> error is thrown and the system default character set is
used as a fallback.</p>
<codeblock outputclass="language-xml">&lt;coderef href="unicode.txt" format="txt; charset=UTF-8"/></codeblock>
<p>As of DITA-OT 3.3, the default character set for code references can be changed by adding the
<parmname>default.coderef-charset</parmname> key to the
<xref keyref="configuration-properties-file">configuration.properties</xref> file:</p>
<codeblock outputclass="language-properties">default.coderef-charset = ISO-8859-1</codeblock>
<p>The character set values are those supported by the Java
<xref
format="html"
href="https://docs.oracle.com/javase/8/docs/api/java/nio/charset/Charset.html"
scope="external"
>Charset</xref> class.</p>
</section>
<section>
<title>Line range extraction</title>
<p>Code references can be limited to extract only a specified line range by defining the
<codeph>line-range</codeph> pointer in the URI fragment. The format is:</p>
<codeblock>uri ("#line-range(" start ("," end)? ")" )?</codeblock>
<p>Start and end line numbers start from 1 and are inclusive. If the end range is omitted, the range ends on the
last line of the file.</p>
</section>
<example>
<codeblock
outputclass="language-xml"
>&lt;coderef href="Parser.scala#line-range(5,10)" format="scala"/></codeblock>
<p>Only lines from 5 to 10 will be included in the output.</p>
</example>
<section>
<title>RFC 5147</title>
<indexterm>RFC 5147</indexterm>
<p>DITA-OT also supports the line position and range syntax from
<xref keyref="rfc5147"/>. The format for line range is:</p>
<codeblock>uri ("#line=" start? "," end? )?</codeblock>
<p>Start and end line numbers start from 0 and are inclusive and exclusive, respectively. If the start range is
omitted, the range starts from the first line; if the end range is omitted, the range ends on the last line of
the file. The format for line position is:</p>
<codeblock>uri ("#line=" position )?</codeblock>
<p>The position line number starts from 0.</p>
</section>
<example>
<codeblock outputclass="language-xml">&lt;coderef href="Parser.scala#line=4,10" format="scala"/></codeblock>
<p>Only lines from 5 to 10 will be included in the output.</p>
</example>
<section>
<title>Line range by content</title>
<p>Instead of specifying line numbers, you can also select lines to include in the code reference by specifying
keywords (or “<term>tokens</term>”) that appear in the referenced file.</p>
<div id="coderef-by-content">
<p>DITA-OT supports the <codeph>token</codeph> pointer in the URI fragment to extract a line range based on the
file content. The format for referencing a range of lines by content is:</p>
<codeblock>uri ("#token=" start? ("," end)? )?</codeblock>
<p>Lines identified using start and end tokens are exclusive: the lines that contain the start token and end
token will be not be included. If the start token is omitted, the range starts from the first line in the
file; if the end token is omitted, the range ends on the last line of the file. </p>
</div>
</section>
<example>
<p>Given a Haskell source file named <filepath>fact.hs</filepath> with the following content,</p>
<codeblock outputclass="language-haskell normalize-space show-line-numbers show-whitespace"><coderef
href="../resources/fact.hs"
/></codeblock>
<p>a range of lines can be referenced as:</p>
<codeblock outputclass="language-xml">&lt;coderef href="fact.hs#token=START-FACT,END-FACT"/></codeblock>
<p>to include the range of lines that follows the <codeph>START-FACT</codeph> token on Line 1, up to (but not
including) the line that contains the <codeph>END-FACT</codeph> token (Line 5). The resulting
<xmlelement>codeblock</xmlelement> would contain lines 2–4:</p>
<codeblock outputclass="language-haskell"><coderef
href="../resources/fact.hs#token=START-FACT,END-FACT"
/></codeblock>
<note type="tip" id="coderef-by-content-tip">This approach can be used to reference code samples that are
frequently edited. In these cases, referencing line ranges by line number can be error-prone, as the target line
range for the reference may shift if preceding lines are added or removed. Specifying ranges by line content
makes references more robust, as long as the <codeph>token</codeph> keywords are preserved when the referenced
resource is modified.</note></example>
<refbodydiv id="normalize-codeblock-whitespace">
<section>
<title>Whitespace normalization</title>
<indexterm>whitespace handling</indexterm>
<p>DITA-OT can adjust the leading whitespace in code blocks to remove excess indentation and keep lines short.
Given an XML snippet in a codeblock with lines that all begin with spaces (indicated here as dots “·”),</p>
</section>
<example>
<p><codeblock outputclass="language-xml">··&lt;subjectdef keys="audience">
····&lt;subjectdef keys="novice"/>
····&lt;subjectdef keys="expert"/>
··&lt;/subjectdef></codeblock></p>
<p>DITA-OT can remove the leading whitespace that is common to all lines in the code block. To trim the excess
space, set the <xmlatt>outputclass</xmlatt> attribute on the <xmlelement>codeblock</xmlelement> element to
include the <codeph>normalize-space</codeph> keyword.</p>
<p>In this case, two spaces (“··”) would be removed from the beginning of each line, shifting content to the
left by two characters, while preserving the indentation of lines that contain additional whitespace (beyond
the common indent):</p>
<p><codeblock outputclass="language-xml">&lt;subjectdef keys="audience">
··&lt;subjectdef keys="novice"/>
··&lt;subjectdef keys="expert"/>
&lt;/subjectdef></codeblock></p>
</example>
</refbodydiv>
<refbodydiv id="visualize-codeblock-whitespace">
<section>
<title>Whitespace visualization (PDF)</title>
<p>DITA-OT can be set to display the whitespace characters in code blocks to visualize indentation in PDF
output.</p>
<p>To enable this feature, set the <xmlatt>outputclass</xmlatt> attribute on the
<xmlelement>codeblock</xmlelement> element to include the <codeph>show-whitespace</codeph> keyword.</p>
<p>When PDF output is generated, space characters in the code will be replaced with a middle dot or “interpunct”
character ( <codeph>·</codeph> ); tab characters are replaced with a rightwards arrow and three spaces
( <codeph>→   </codeph> ).</p>
</section>
<example deliveryTarget="pdf">
<fig>
<title>Sample Java code with visible whitespace characters <i>(PDF only)</i></title>
<codeblock outputclass="language-java show-whitespace"> for i in 0..10 {
println(i)
}</codeblock>
</fig>
</example>
</refbodydiv>
<refbodydiv id="codeblock-line-numbers">
<section>
<title>Line numbering (PDF)</title>
<indexterm>line numbering</indexterm>
<p>DITA-OT can be set to add line numbers to code blocks to make it easier to distinguish specific lines.</p>
<p>To enable this feature, set the <xmlatt>outputclass</xmlatt> attribute on the
<xmlelement>codeblock</xmlelement> element to include the <codeph>show-line-numbers</codeph> keyword.</p>
</section>
<example deliveryTarget="pdf">
<fig>
<title>Sample Java code with line numbers and visible whitespace characters <i>(PDF only)</i></title>
<codeblock outputclass="language-java show-line-numbers show-whitespace"> for i in 0..10 {
println(i)
}</codeblock>
</fig>
</example>
</refbodydiv>
</refbody>
</reference>

207
dita-ot-3.6/docsrc/reference/flagging-migration.dita Normal file
View file

@ -0,0 +1,207 @@
<?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="flagging-migration" rev="1.7">
<title>XHTML migration for flagging updates in DITA-OT 1.7</title>
<titlealts>
<navtitle>Flagging updates</navtitle>
</titlealts>
<shortdesc>This topic is primarily of interest to developers with XHTML transform overrides written prior to DITA-OT
1.7. Due to significant changes in the flagging process with the 1.7 release, some changes may be needed to make
overrides work properly with DITAVAL-based flagging. The new design is significantly simpler than the old design; in
many cases, migration will consist of deleting old code that is no longer needed.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm><xmlelement>ul</xmlelement></indexterm>
<indexterm>deprecated features
<indexterm><codeph>mode="elementname-fmt"</codeph></indexterm></indexterm>
<indexterm>deprecated features
<indexterm><codeph>DITAVAL templates</codeph></indexterm></indexterm>
<indexterm>DITAVAL
<indexterm>template changes in 1.7</indexterm></indexterm>
<indexterm>CSS
<indexterm>gen-style</indexterm></indexterm>
<indexterm>flagging</indexterm>
</keywords>
</metadata>
</prolog>
<refbody>
<section>
<title>Which XHTML overrides need to migrate?</title>
<p>If your override does not contain any code related to DITAVAL flagging, then there is nothing to migrate.</p>
<p>If your builds do not make use of DITAVAL-based flagging, but call the deprecated flagging templates, then you
should override but there is little urgency. You will not see any difference in the output, but those templates
will be removed in a future release.</p>
<p>If you do make use of DITAVAL-based flagging, try using your override with 1.7. Check the elements you
override:
<ol>
<li>In some cases flags may be doubled. This will be the case if you call routines such as
<codeph>"start-flagit"</codeph>.</li>
<li>In some cases flags may be removed. This will be the case if you call shortcut routines such as
<codeph>"revtext"</codeph> or <codeph>"revblock"</codeph>.</li>
<li>In other cases, flags may still appear properly, in which case migration is less urgent.</li>
</ol></p>
<p>For any override that needs migration, please see the instructions that follow.</p></section>
<section>
<title>Deprecated templates in DITA-OT 1.7</title>
<p>All of the old DITAVAL based templates are deprecated in DITA-OT 1.7. If your overrides include any of the
following templates, they should be migrated for the new release; in many cases the templates below will not
have any effect on your output, but all instances should be migrated.</p>
<ul>
<li>The <codeph>"gen-style"</codeph> template used to add CSS styling</li>
<li>The <codeph>"start-flagit"</codeph> and <codeph>"end-flagit"</codeph> templates used to generate image flags
based on property attributes like @audience</li>
<li>The <codeph>"start-revflag"</codeph> and <codeph>"end-revflag"</codeph> templates, used to generate images
for active revisions</li>
<li>Shortcut templates that group these templates into a single call, such as:
<ul>
<li><codeph>"start-flags-and-rev"</codeph> and <codeph>"end-flags-and-rev"</codeph>, used to combine flags
and revisions into one call</li>
<li><codeph>"revblock"</codeph> and <codeph>"revtext"</codeph>, both used to output start revisions, element
content, and end revisions</li>
<li>The modes <codeph>"outputContentsWithFlags"</codeph> and
<codeph>"outputContentsWithFlagsAndStyle"</codeph>, both used to combine processing for
property/revision flags with content processing</li>
</ul></li>
<li>All other templates that make use of the <codeph>$flagrules</codeph> variable, which is no longer used in
any of the DITA-OT 1.7 code</li>
<li>All templates within <filepath>flag.xsl</filepath> that were called from the templates listed above</li>
<li>Element processing handled with mode="elementname-fmt", such as <codeph>mode="ul-fmt"</codeph> for
processing unordered lists and <codeph>mode="section-fmt"</codeph> for sections.</li>
</ul></section>
<section>
<title>What replaces the templates?</title>
<p>The new flagging design described in the preprocess design section now adds literal copies of relevant DITAVAL
elements, along with CSS based flagging information, into the relevant section of the topic. This allows most
flags to be processed in document order; in addition, there is never a need to read the DITAVAL, interpret CSS,
or evaluate flagging logic. The <filepath>htmlflag.xsl</filepath> file contains a few rules to match and process
the start/end flags; in most cases, all code to explicitly process flags can be deleted.</p>
<p>For example, the common logic for most element rules before DITA-OT 1.7 could be boiled down to the following:
<ol>
<li>Match element </li>
<li>Create <codeph>"flagrules"</codeph> variable by reading DITAVAL for active flags </li>
<li>Output start tag such as <codeph>&lt;div></codeph> or <codeph>&lt;span></codeph>
</li>
<li>Call <codeph>"commonattributes"</codeph> and ID processing </li>
<li>Call <codeph>"gen-style"</codeph> with <codeph>$flagrules</codeph>, to create DITAVAL based CSS </li>
<li>Call <codeph>"start-flagit"</codeph> with <codeph>$flagrules</codeph>, to create start flag images </li>
<li>Call <codeph>"start-revflag"</codeph> with <codeph
>$flagrules</codeph>, to create start revision images </li>
<li>Output contents </li>
<li>Call <codeph>"end-revflag"</codeph> with <codeph>$flagrules</codeph>, to create end revision images </li>
<li>Call <codeph>"end-flagit"</codeph> with <codeph>$flagrules</codeph>, to create end flag images </li>
<li>Output end tag such as <codeph>&lt;/div></codeph> or <codeph>&lt;/span></codeph></li>
</ol>
</p>
<p>In DITA-OT 1.7, style and images are typically handled with XSLT fallthrough processing. This removes virtually
all special flag coding from element rules, because flags are already part of the document and processed in
document order. </p>
<p>The sample above is reduced to:
<ol>
<li>Match element </li>
<li>Output start tag such as <codeph>&lt;div></codeph> or <codeph>&lt;span></codeph>
</li>
<li>Call <codeph>"commonattributes"</codeph> and ID processing </li>
<li>Output contents </li>
<li>Output end tag such as <codeph>&lt;/div></codeph> or <codeph>&lt;/span></codeph></li>
</ol>
</p>
</section>
<section>
<title>Migrating <codeph>"gen-style"</codeph> named template</title>
<p>Calls to the <codeph>"gen-style"</codeph> template should be deleted. There is no need to replace this call for
most elements.</p>
<p>The <codeph>"gen-style"</codeph> template was designed to read a DITAVAL file, find active style-based flagging
(such as colored or bold text), and add it to the generated @style attribute in HTML.</p>
<p>With DITA-OT 1.7, the style is calculated in the pre-process flagging module. The result is created as
@outputclass on a <codeph>&lt;ditaval-startprop></codeph> sub-element. The <codeph>"commonattributes"</codeph>
template now includes a line to process that value; the result is that for every element that calls
<codeph>"commonattributes"</codeph>, DITAVAL style will be processed when needed. Because virtually every
element includes a call to this common template, there is little chance that your override needs to explicitly
process the style. The new line in <codeph>"commonattributes"</codeph> that handles the style is:
<codeblock
outputclass="language-xml"
>&lt;xsl:apply-templates select="*[contains(@class,' ditaot-d/ditaval-startprop ')]/@outputclass" mode="add-ditaval-style"/></codeblock></p></section>
<section>
<title>Migrating <codeph>"start-flagit"</codeph>, <codeph>"start-revflag"</codeph>, <codeph>"end-flagit"</codeph>,
and <codeph>"end-flagit"</codeph> named templates</title>
<p>Calls to these templates fall into two general groups.</p>
<p>If the flow of your element rule is to create a start tag like <codeph>&lt;div></codeph>,
<codeph>"start-flagit"</codeph>/<codeph>"start-revflag"</codeph>, process contents,
<codeph>"end-revflag"</codeph>/<codeph>"end-flagit"</codeph>, end tag - you just need to delete the calls to
these templates. Flags will be generated simply by processing the element contents in document order.</p>
<p>If the flow of your element rule processes flags outside of the normal document-order. There are generally two
reasons this is done. The first case is for elements like <codeph>&lt;ol></codeph>, where flags must appear
before the <codeph>&lt;ol></codeph> in order to create valid XHTML. The second is for elements like
<codeph>&lt;section></codeph>, where start flags are created, followed by the title or some generated text,
element contents, and finally end flags. In either of these cases, support for processing flags in document
order is disabled, so they must be explicitly processed out-of-line.</p>
<p>This is done with the following two lines (one for start flag/revision, one for end flag/revision):</p>
<ul>
<li>
<p>Create starting flag and revision images:</p>
<codeblock
outputclass="language-xml"
>&lt;xsl:apply-templates select="*[contains(@class,' ditaot-d/ditaval-startprop ')]" mode="out-of-line"/></codeblock></li>
<li>
<p>Create ending flag and revision images:</p>
<codeblock
outputclass="language-xml"
>&lt;xsl:apply-templates select="*[contains(@class,' ditaot-d/ditaval-endprop ')]" mode="out-of-line"/></codeblock></li>
</ul>
<p>For example, the following lines are used in DITA-OT 1.7 to process the <xmlelement>ul</xmlelement> element
(replacing the 29 lines used in DITA-OT
1.6):<codeblock
outputclass="language-xml normalize-space show-line-numbers show-whitespace"
>&lt;xsl:template match="*[contains(@class,' topic/ul ')]">
<b>&lt;xsl:apply-templates select="*[contains(@class,' ditaot-d/ditaval-startprop ')]" mode="out-of-line"/></b>
&lt;xsl:call-template name="setaname"/>
&lt;ul>
&lt;xsl:call-template name="commonattributes"/>
&lt;xsl:apply-templates select="@compact"/>
&lt;xsl:call-template name="setid"/>
&lt;xsl:apply-templates/>
&lt;/ul>
<b>&lt;xsl:apply-templates select="*[contains(@class,' ditaot-d/ditaval-endprop ')]" mode="out-of-line"/></b>
&lt;xsl:value-of select="$newline"/>
&lt;/xsl:template></codeblock></p></section>
<section>
<title>Migrating <codeph>"start-flags-and-rev"</codeph> and <codeph>"end-flags-and-rev"</codeph></title>
<ul>
<li><codeph>"start-flags-and-rev"</codeph> is equivalent to calling <codeph>"start-flagit"</codeph> followed by
<codeph>"start-revflag"</codeph>; it should be migrated as in the previous section.</li>
<li><codeph>"end-flags-and-rev"</codeph> is equivalent to calling <codeph>"end-revflag"</codeph> followed by
<codeph>"end-flagit"</codeph>; it should be migrated as in the previous section.</li>
</ul></section>
<section>
<title>Migrating <codeph>"revblock"</codeph> and <codeph>"revtext"</codeph></title>
<p>Calls to these two templates can be replaced with a simple call to
<codeph>&lt;xsl:apply-templates/></codeph>.</p></section>
<section>
<title>Migrating modes <codeph>"outputContentsWithFlags"</codeph> and
<codeph>"outputContentsWithFlagsAndStyle"</codeph></title>
<p>Processing an element with either of these modes can be replaced with a simple call to
<codeph>&lt;xsl:apply-templates/></codeph>.</p></section>
<section>
<title>Migrating <codeph>mode="elementname-fmt"</codeph></title>
<p>Prior to DITA-OT 1.7, many elements were processed with the following
logic:<pre>Match element
Set variable to determine if revisions are active and $DRAFT is on
If active
create division with rev style
process element with mode="elementname-fmt"
end division
Else
process element with mode="elementname-fmt"
Match element with mode="elementname-fmt"
Process as needed</pre></p>
<p>Beginning with DITA-OT 1.7, styling from revisions is handled automatically with the
<codeph>"commonattributes"</codeph> template. This means there is no need for the extra testing, or the
indirection to <codeph>mode="elementname-fmt"</codeph>. These templates are deprecated, and element processing
will move into the main element rule. Overrides that include this indirection may remove it; overrides should
also be sure to match the default rule, rather than matching with
<codeph>mode="elementname-fmt"</codeph>.</p></section>
</refbody>
</reference>

7
dita-ot-3.6/docsrc/reference/gloss-argument.dita Normal file
View file

@ -0,0 +1,7 @@
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE glossentry PUBLIC "-//OASIS//DTD DITA Glossary//EN" "glossary.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<glossentry id="gloss-argument">
<glossterm>argument</glossterm>
<glossdef>Required parameter passed to the Ant process or <cmdname>dita</cmdname> command.</glossdef>
</glossentry>

28
dita-ot-3.6/docsrc/reference/gloss-dita-open-toolkit.dita Normal file
View file

@ -0,0 +1,28 @@
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE glossentry PUBLIC "-//OASIS//DTD DITA Glossary//EN" "glossary.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<glossentry id="gloss-dita-open-toolkit">
<glossterm>DITA Open Toolkit</glossterm>
<glossdef>The open-source publishing engine for content authored in the Darwin Information Typing
Architecture.</glossdef>
<prolog>
<metadata>
<keywords>
<indexterm>DOST</indexterm>
</keywords>
</metadata>
</prolog>
<glossBody>
<glossPartOfSpeech value="proper-noun"/>
<glossAlt>
<glossAbbreviation>DITA-OT</glossAbbreviation>
<glossUsage>Treat as a proper noun; do not precede with <i>the</i> definite article.</glossUsage>
</glossAlt>
<glossAlt>
<glossAcronym>DOST</glossAcronym>
<glossStatus value="deprecated"/>
<glossUsage>Deprecated acronym for “<b>D</b>ITA <b>O</b>pen <i><b>S</b>ource</i>
<b>T</b>oolkit”. Use <term>DITA-OT</term> instead.</glossUsage>
</glossAlt>
</glossBody>
</glossentry>

10
dita-ot-3.6/docsrc/reference/gloss-extension-point.dita Normal file
View file

@ -0,0 +1,10 @@
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE glossentry PUBLIC "-//OASIS//DTD DITA Glossary//EN" "glossary.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<glossentry id="gloss-extension-point">
<glossterm>extension point</glossterm>
<glossdef>Pre-defined interface that can be added to a plug-in to allow other plug-ins to extend or customize portions
of its functionality. An extendable feature is defined by declaring an <xmlelement>extension-point</xmlelement>
element in the <filepath>plugin.xml</filepath> file. Other plug-ins can then override the default behavior by
defining custom code that runs when this extension point is called.</glossdef>
</glossentry>

7
dita-ot-3.6/docsrc/reference/gloss-option.dita Normal file
View file

@ -0,0 +1,7 @@
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE glossentry PUBLIC "-//OASIS//DTD DITA Glossary//EN" "glossary.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<glossentry id="gloss-option">
<glossterm>option</glossterm>
<glossdef>Discretionary parameter passed to the Ant process or <cmdname>dita</cmdname> command.</glossdef>
</glossentry>

7
dita-ot-3.6/docsrc/reference/gloss-output-format.dita Normal file
View file

@ -0,0 +1,7 @@
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE glossentry PUBLIC "-//OASIS//DTD DITA Glossary//EN" "glossary.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<glossentry id="gloss-output-format">
<glossterm>output format</glossterm>
<glossdef>Deliverable file or set of files containing all of the transformed content.</glossdef>
</glossentry>

7
dita-ot-3.6/docsrc/reference/gloss-parameter.dita Normal file
View file

@ -0,0 +1,7 @@
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE glossentry PUBLIC "-//OASIS//DTD DITA Glossary//EN" "glossary.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<glossentry id="gloss-parameter">
<glossterm>parameter</glossterm>
<glossdef>Command-line argument or option passed to the Ant process or <cmdname>dita</cmdname> command.</glossdef>
</glossentry>

7
dita-ot-3.6/docsrc/reference/gloss-plug-in.dita Normal file
View file

@ -0,0 +1,7 @@
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE glossentry PUBLIC "-//OASIS//DTD DITA Glossary//EN" "glossary.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<glossentry id="gloss-plug-in">
<glossterm>plug-in</glossterm>
<glossdef>Group of related files that change the default behavior of DITA-OT in some way.</glossdef>
</glossentry>

8
dita-ot-3.6/docsrc/reference/gloss-processor.dita Normal file
View file

@ -0,0 +1,8 @@
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE glossentry PUBLIC "-//OASIS//DTD DITA Glossary//EN" "glossary.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<glossentry id="gloss-processor">
<glossterm>processor</glossterm>
<glossdef>Software that performs a series of operations to transform DITA content from one format to
another.</glossdef>
</glossentry>

7
dita-ot-3.6/docsrc/reference/gloss-property.dita Normal file
View file

@ -0,0 +1,7 @@
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE glossentry PUBLIC "-//OASIS//DTD DITA Glossary//EN" "glossary.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<glossentry id="gloss-property">
<glossterm>property</glossterm>
<glossdef>Ant-specific argument or option.</glossdef>
</glossentry>

10
dita-ot-3.6/docsrc/reference/gloss-template-plugin.dita Normal file
View file

@ -0,0 +1,10 @@
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE glossentry PUBLIC "-//OASIS//DTD DITA Glossary//EN" "glossary.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<glossentry id="gloss-template-plugin">
<glossterm>template</glossterm>
<glossdef>Optional <xmlelement>template</xmlelement> elements can be added to <filepath>plugin.xml</filepath> files to
define XML or XSL files that integrate DITA-OT extensions. Template files are often named with a
<filepath>_template</filepath> suffix, and may be used to create custom extensions, group targets, and more.
Anything contained in the plug-in’s template files is integrated when the plug-in is installed.</glossdef>
</glossentry>

7
dita-ot-3.6/docsrc/reference/gloss-template-xslt.dita Normal file
View file

@ -0,0 +1,7 @@
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE glossentry PUBLIC "-//OASIS//DTD DITA Glossary//EN" "glossary.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<glossentry id="gloss-template-xslt">
<glossterm>XSL template</glossterm>
<glossdef>Set of rules in an XSL stylesheet that are applied to nodes that match specific XML structures.</glossdef>
</glossentry>

16
dita-ot-3.6/docsrc/reference/gloss-transformation-type.dita Normal file
View file

@ -0,0 +1,16 @@
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE glossentry PUBLIC "-//OASIS//DTD DITA Glossary//EN" "glossary.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<glossentry id="gloss-transformation-type">
<glossterm>transformation type</glossterm>
<glossdef>Component of a plug-in that defines an output format.</glossdef>
<glossBody>
<glossAlt>
<glossAbbreviation>transtype</glossAbbreviation>
<glossUsage>Abbreviated form of <term>transformation type</term>. Use only to refer to the
<parmname>transtype</parmname> parameter of the <cmdname>dita</cmdname> command, or to the
<xmlelement>transtype</xmlelement> element in a <filepath>plugin.xml</filepath> file that defines the output
format.</glossUsage>
</glossAlt>
</glossBody>
</glossentry>

7
dita-ot-3.6/docsrc/reference/gloss-transtype.dita Normal file
View file

@ -0,0 +1,7 @@
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE glossentry PUBLIC "-//OASIS//DTD DITA Glossary//EN" "glossary.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<glossentry id="gloss-transtype">
<glossterm>transtype</glossterm>
<glossdef>Specific element of <filepath>plugin.xml</filepath>.</glossdef>
</glossentry>

8
dita-ot-3.6/docsrc/reference/gloss-variable.dita Normal file
View file

@ -0,0 +1,8 @@
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE glossentry PUBLIC "-//OASIS//DTD DITA Glossary//EN" "glossary.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<glossentry id="gloss-variable">
<glossterm>variable</glossterm>
<glossdef>Language-specific piece of generated text, most often defined in the files in
<filepath>org.dita.base\xsl\common</filepath>.</glossdef>
</glossentry>

7
dita-ot-3.6/docsrc/reference/glossary.dita Normal file
View file

@ -0,0 +1,7 @@
<?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="glossary">
<title>Glossary</title>
<shortdesc>Certain terms have particular meaning in the context of the DITA Open Toolkit project.</shortdesc>
</concept>

21
dita-ot-3.6/docsrc/reference/glossary.ditamap Normal file
View file

@ -0,0 +1,21 @@
<?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>Glossary entries</title>
<topicref keyref="glossary" chunk="to-content">
<glossref href="gloss-argument.dita" keys="gloss-argument" print="yes" toc="yes"/>
<glossref href="gloss-dita-open-toolkit.dita" keys="gloss-dita-open-toolkit" print="yes" toc="yes"/>
<glossref href="gloss-extension-point.dita" keys="gloss-extension-point" print="yes" toc="yes"/>
<glossref href="gloss-option.dita" keys="gloss-option" print="yes" toc="yes"/>
<glossref href="gloss-output-format.dita" keys="gloss-output-format" print="yes" toc="yes"/>
<glossref href="gloss-parameter.dita" keys="gloss-parameter" print="yes" toc="yes"/>
<glossref href="gloss-plug-in.dita" keys="gloss-plug-in" print="yes" toc="yes"/>
<glossref href="gloss-processor.dita" keys="gloss-processor" print="yes" toc="yes"/>
<glossref href="gloss-property.dita" keys="gloss-property" print="yes" toc="yes"/>
<glossref href="gloss-template-plugin.dita" keys="gloss-template-plugin" print="yes" toc="yes"/>
<glossref href="gloss-transformation-type.dita" keys="gloss-transformation-type" print="yes" toc="yes"/>
<glossref href="gloss-variable.dita" keys="gloss-variable" print="yes" toc="yes"/>
<glossref href="gloss-template-xslt.dita" keys="gloss-template-xslt" print="yes" toc="yes"/>
</topicref>
</map>

24
dita-ot-3.6/docsrc/reference/html-based-processing.dita Normal file
View file

@ -0,0 +1,24 @@
<?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="xhtmlwithnavigation">
<title>HTML-based processing modules</title>
<shortdesc>DITA-OT ships with several varieties of HTML output, each of which follows roughly the same path through
the processing pipeline. All HTML-based transformations begin with the same call to the pre-processing module, after
which they generate HTML files and then branch to create the transformation-specific navigation files.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>HTML
<indexterm>various output types</indexterm></indexterm>
<indexterm>pipelines
<indexterm>HTML</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<conbody>
<section>
<draft-comment author="Kristen Eberlein" time="29 March 2013">Does the content in this section pertain to the
<codeph>dita.map.xhtml</codeph> target?</draft-comment></section>
</conbody>
</concept>

31
dita-ot-3.6/docsrc/reference/html5-processing.dita Normal file
View file

@ -0,0 +1,31 @@
<?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>HTML5 processing</title>
<shortdesc>After the HTML5 files are generated, the <option>html5</option> transformation generates a table of
contents (ToC) file called <filepath>index.html</filepath>, which can be loaded as a cover page or rendered in a
navigation sidebar or menu via CSS.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>HTML
<indexterm>HTML5</indexterm></indexterm>
<indexterm>HTML5
<indexterm>CSS</indexterm>
<indexterm>nav-toc</indexterm></indexterm>
<indexterm>targets
<indexterm>HTML5</indexterm></indexterm>
<indexterm>nav-toc</indexterm>
<indexterm>CSS
<indexterm>HTML5</indexterm></indexterm>
<indexterm>entry file
<indexterm>HTML5</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<conbody>
<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>
</conbody>
</concept>

45
dita-ot-3.6/docsrc/reference/htmlhelp-processing.dita Normal file
View file

@ -0,0 +1,45 @@
<?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="xhtmlchm">
<title>HTML Help processing</title>
<shortdesc>The <option>htmlhelp</option> transformation creates HTML Help control files. If the build runs on a system
that has the HTML Help compiler installed, the control files are compiled into a CHM file.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>HTML
<indexterm>CHM</indexterm></indexterm>
<indexterm>dita.map.htmlhelp</indexterm>
<indexterm>targets
<indexterm>HTML Help</indexterm></indexterm>
<indexterm><filepath>.hhp</filepath></indexterm>
<indexterm><filepath>.hhc</filepath></indexterm>
<indexterm><filepath>.hhk</filepath></indexterm>
<indexterm>HTML Help</indexterm>
</keywords>
</metadata>
</prolog>
<conbody>
<section>
<p>Once the pre-processing and XHTML processes are completed, most of the HTML Help processing is handled by the
following targets:</p>
<dl>
<dlentry>
<dt><codeph>dita.map.htmlhelp</codeph></dt>
<dd>Create the HHP, HHC, and HHK files. The HHK file is sorted based on the language of the map.</dd>
</dlentry>
<dlentry>
<dt><codeph>dita.htmlhelp.convertlang</codeph></dt>
<dd>Ensures that the content can be processed correctly by the compiler, and that the appropriate code pages
and languages are used.</dd>
</dlentry>
<dlentry>
<dt><codeph>compile.HTML.Help</codeph></dt>
<dd>Attempts to detect the HTML Help compiler. If the compiler is found, the full project is compiled into a
single CHM file.</dd>
</dlentry>
</dl>
</section>
</conbody>
</concept>

BIN
dita-ot-3.6/docsrc/reference/images/processing-flow.graffle Normal file
View file

Binary file not shown.

1
dita-ot-3.6/docsrc/reference/images/processing-flow.svg Normal file
View file

File diff suppressed because one or more lines are too long
Side by side

After

Width:  |  Height:  |  Size: 18 KiB

124
dita-ot-3.6/docsrc/reference/implementation-dependent-features.dita Normal file
View file

@ -0,0 +1,124 @@
<?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="implementation-dependent-features">
<title>Implementation-dependent features</title>
<shortdesc>For certain features, the DITA specification allows conforming processors to choose between different
implementation alternatives. In these cases, there may be differences in behavior when DITA content is handled by
different processors. DITA-OT supports implementation-specific features by applying one or more of the permissible
processing approaches.</shortdesc>
<prolog>
<metadata>
<keywords> </keywords>
</metadata>
</prolog>
<refbody>
<section id="section_jla_oqn_qc">
<title>Chunking</title>
<indexterm><xmlatt>chunk</xmlatt>
<indexterm>supported methods</indexterm></indexterm>
<indexterm><xmlatt>chunk</xmlatt>
<indexterm>error recovery</indexterm></indexterm>
<p>DITA content can be divided or merged into new output documents in different ways, depending on the value of
the <xmlatt>chunk</xmlatt> attribute.</p>
<p>DITA-OT supports the following chunking methods:</p>
<ul>
<li>select-topic</li>
<li>select-document</li>
<li>select-branch</li>
<li>by-topic</li>
<li>by-document</li>
<li>to-content</li>
<li>to-navigation.</li>
</ul>
<p>When no chunk attribute values are given, no chunking is performed.</p>
<note>For HTML-based transformation types, this is effectively equivalent to select-document and by-document
defaults.</note>
<p>Error recovery:</p>
<ul>
<li>When two tokens from the same category are used, no error or warning is thrown.<draft-comment>This violates
DITA 1.2 spec.</draft-comment></li>
<li>When an unrecognized chunking method is used, no error or warning is thrown.</li>
</ul>
</section>
<section id="section_zaa_bgs_qc">
<title>Filtering</title>
<indexterm><xmlelement>revprop</xmlelement></indexterm>
<indexterm><xmlatt>val</xmlatt></indexterm>
<indexterm>filters
<indexterm>duplicate conditions</indexterm></indexterm>
<p>Error recovery:</p>
<ul>
<li>When there are multiple <xmlelement>revprop</xmlelement> elements with the same <xmlatt>val</xmlatt>
attribute, no error or warning is thrown</li>
<li>When multiple prop elements define a duplicate attribute and value combination, attribute default, or
fall-back behavior, the <msgnum>DOTJ007W</msgnum> warning is thrown.</li>
</ul>
</section>
<section id="section_kjq_egs_qc">
<title>Debugging attributes</title>
<indexterm>debugging
<indexterm>attributes</indexterm>
<indexterm>xtrf</indexterm>
<indexterm>xtrc</indexterm></indexterm>
<indexterm>xtrf</indexterm>
<indexterm>xtrc</indexterm>
<p>The debug attributes are populated as follows:</p>
<dl>
<dlentry>
<dt>xtrf</dt>
<dd>The XML trace filename is used to store the absolute system path of the original source document.</dd>
</dlentry>
<dlentry>
<dt>xtrc</dt>
<dd>The XML trace counter stores an element counter with the following format:
<codeblock>element-name ":" integer-counter ";" line-number ":" column-number</codeblock></dd>
</dlentry>
</dl>
</section>
<section id="section_dco_qgs_qc">
<title>Image scaling</title>
<indexterm>images
<indexterm>scaling</indexterm></indexterm>
<p>If both height and width attributes are given, the image is scaled non-uniformly.</p>
<p>If the scale attribute is not an unsigned integer, no error or warning is thrown during preprocessing.</p>
</section>
<section>
<title>Map processing</title>
<indexterm><xmlelement>topicref</xmlelement></indexterm>
<indexterm>map processing</indexterm>
<p>When a <xmlelement>topicref</xmlelement> element that references a map contains child
<xmlelement>topicref</xmlelement> elements, the <msgnum>DOTX068W</msgnum> error is thrown and the child
<xmlelement>topicref</xmlelement> elements are ignored. </p>
</section>
<section id="section_h3h_jsx_1h">
<title>Link processing</title>
<indexterm><xmlatt>href</xmlatt></indexterm>
<indexterm>link processing</indexterm>
<p>When the value of a hyperlink reference in the <xmlatt>href</xmlatt> attribute is not a valid URI reference,
the <msgnum>DOTJ054E</msgnum> error is thrown. Depending on the
<xref href="../parameters/parameters-base.dita#base/processing-mode">processing-mode</xref> setting, error
recovery may be attempted.</p>
</section>
<section>
<title>Copy-to processing</title>
<indexterm><xmlelement>shortdesc</xmlelement></indexterm>
<indexterm><xmlatt>copy-to</xmlatt></indexterm>
<p>When the <xmlatt>copy-to</xmlatt> attribute is specified on a <xmlelement>topicref</xmlelement>, the content of
the <xmlelement>shortdesc</xmlelement> element is not used to override the short description of the topic.</p>
</section>
<section>
<title>Coderef processing</title>
<indexterm><xmlelement>coderef</xmlelement></indexterm>
<indexterm>encoding</indexterm>
<p>When <xmlelement>coderef</xmlelement> elements are used within code blocks to reference external files with
literal code samples, the system default character set is used as the target file encoding unless a different
character set is explicitly defined via the mechanisms described under
<xref href="extended-functionality.dita#code-reference/coderef-charset"/>.</p>
</section>
</refbody>
</reference>

8
dita-ot-3.6/docsrc/reference/index.dita Normal file
View file

@ -0,0 +1,8 @@
<?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="reference">
<title>Reference</title>
<shortdesc>The <cite>Reference</cite> topics provide more advanced information about the DITA-OT architecture, OASIS
specification support, and licensing.</shortdesc>
</concept>

76
dita-ot-3.6/docsrc/reference/java-api.dita Normal file
View file

@ -0,0 +1,76 @@
<?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="API">
<title>Using the Java API</title>
<shortdesc>DITA Open Toolkit includes a Java Application Programming Interface to allow developers to embed the
toolkit more easily into other Java programs.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>Java
<indexterm>API</indexterm></indexterm>
<indexterm>API</indexterm>
<indexterm><cmdname>dita</cmdname> command
<indexterm>classpath</indexterm></indexterm>
<indexterm>Java
<indexterm>classpath</indexterm></indexterm>
<indexterm>classpath
<indexterm>Java</indexterm>
<indexterm><cmdname>dita</cmdname> command</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<conbody>
<p>When using the API, programmers don’t need to know or care that DITA-OT uses Ant, they can just use Java. </p>
<note>When running DITA-OT via the <cmdname>dita</cmdname> command, an <codeph>ant</codeph> shell script handles the
classpath setup, but when using the API the classpath should be set up as part of the normal classpath
configuration for the Java application.</note>
<example>
<title>Example usage</title>
<codeblock
outputclass="language-java normalize-space show-line-numbers show-whitespace"
>// Create a reusable processor factory with DITA-OT base directory
ProcessorFactory pf = ProcessorFactory.newInstance(ditaDir);
// and set the temporary directory
pf.setBaseTempDir(tempDir);
// Create a processor using the factory and configure the processor
Processor p = pf.newProcessor("html5")
.setInput(mapFile)
.setOutputDir(outDir)
.setProperty("nav-toc", "partial");
// Run conversion
p.run();</codeblock>
</example>
<section>
<indexterm>debugging
<indexterm>logging</indexterm></indexterm>
<p>By default, running DITA-OT via the API will write a debug log to the temporary directory. A custom SLF4J
logger can also be used to access the log via the Simple Logging Facade for Java.</p>
<p>The processor cleans the temporary directory by default, but this can be disabled to simplify debugging in
cases where the processor failed.</p>
<note type="tip">See the <cite>DITA-OT Java API documentation</cite> in the <filepath>doc/api/</filepath> folder
of the DITA-OT distribution package for information on the packages, classes, interfaces and methods provided by
the Java API.</note>
</section>
<section>
<title>Downloading DITA-OT from Maven Central</title>
<indexterm>Maven Central</indexterm>
<p>As of version 2.5, the DITA Open Toolkit base library (<filepath>dost.jar</filepath>) is available via the
Maven 2 Central Repository. You can use this mechanism to download the main JAR file and include it in the build
for other Java projects.</p>
<p>To locate the latest version,
<xref
href="https://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.dita-ot%22"
format="html"
scope="external"
>search for the <codeph>org.dita-ot</codeph> group ID</xref>.</p>
<note type="important">The <filepath>dost.jar</filepath> file provides only the DITA Open Toolkit base library. It
does <b>not</b> contain the full DITA-OT distribution and cannot be used to run DITA-OT by itself. You will need
to ensure that your build installs the other files and directories required for the toolkit along with the
dependencies for your project.</note>
</section>
</conbody>
</concept>

26
dita-ot-3.6/docsrc/reference/license.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="ID">
<title>License Information</title>
<titlealts>
<navtitle>License</navtitle>
</titlealts>
<shortdesc>
<ph id="ph_docs-license-desc">DITA Open Toolkit is released under the Apache License, Version 2.0.</ph>
</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>license</indexterm>
<indexterm>Apache licence</indexterm>
</keywords>
</metadata>
</prolog>
<conbody>
<note>For information on the terms and conditions for use, reproduction, and distribution of DITA Open Toolkit,
refer to the
<xref keyref="license-apache-2"/>.</note>
</conbody>
</concept>

10
dita-ot-3.6/docsrc/reference/license.ditamap Normal file
View file

@ -0,0 +1,10 @@
<?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>License Information</title>
<topicref keyref="license">
<topicref keyref="third-party-software"/>
</topicref>
</map>

131
dita-ot-3.6/docsrc/reference/map-first-preprocessing.dita Normal file
View file

@ -0,0 +1,131 @@
<?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" rev="3.0">
<title>Map-first preprocessing</title>
<titlealts>
<navtitle>Map-first preprocessing</navtitle>
</titlealts>
<shortdesc><ph id="map-first-preproc-desc">DITA-OT 3.0 provides a map-first preprocessing option as an alternative to
the default <codeph>preprocess</codeph> operation. The method, which was introduced in DITA-OT 2.5 as an
experimental feature, has been improved and is ready for use in many production scenarios. Map-first-preprocessing
provides the same functionality as the default <codeph>preprocess</codeph>, but takes a different
approach.</ph></shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>filters
<indexterm>map-first preprocessing</indexterm></indexterm>
<indexterm>preprocessing
<indexterm>map first</indexterm></indexterm>
<indexterm>DITA 1.0</indexterm>
<indexterm>DITA 1.2</indexterm>
<indexterm>DITA 1.3
<indexterm>effect on preprocessing</indexterm></indexterm>
<indexterm>pipelines
<indexterm>map first</indexterm></indexterm>
<indexterm>validate</indexterm>
<indexterm>maps
<index-see>DITA maps</index-see></indexterm>
<indexterm>DITA maps
<indexterm>validate</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<conbody>
<p id="map-first-preproc-gain">Whereas the default preprocessing routine handles both maps and topics at the same
time, often switching back and forth between map operations and topic operations, the map-first approach only
begins processing topics after nearly all map processing is complete. This simplifies the processing logic and
creates cleaner module responsibilities, which makes it easier to process only those topics that are actually
referenced after filtering, for example, or to only process the map to validate the map structure.</p>
<p>The current preprocessing architecture was established during the DITA 1.0 era when there were fewer DITA
features that operated on the map level. Initially, the difference between processing modes was not that great.
DITA 1.2 and 1.3 introduced many more map-level features, such as keys and key scopes, that make it difficult to
reliably work with topics before all map features have been resolved. </p>
<p>The original preprocessing operation already handles many map operations first, but this was not the original
design and requires regular refactoring to handle edge cases. The new map-first preprocessing is designed with
this model in mind, improving the overall processing flow and making it more formal about the map-first model. The
new model also takes advantage of hashed topic file names in the temporary directory, which simplifies many
processing steps, and is better able to handle topics referenced outside of the map directory (that case has
resulted in a variety of issues with the original model).</p>
<note id="map-first-preproc-note">The map-first preprocessing option is enabled by default in DITA-OT 3.0 for PDF
and HTML Help. These formats were chosen because they generate a compiled result file, so temporarily hashed file
names should all be invisible to the build. After further testing and feedback, the new option will most likely
become the default for other output formats in future versions. Because the DITA-OT development team cannot have
access to all varieties of DITA, all edge cases, or even all the ways DITA-OT itself is extended, the switch to
default map-first preprocessing for other output formats will be smoother for everyone if more people can test and
provide feedback.</note>
<section>
<title>How to use map-first preprocessing</title>
<p>To use (or test) map-first preprocessing, call the <codeph>preprocess2</codeph> Ant target in your custom
transformation types instead of using the default <codeph>preprocess</codeph> target.</p>
<p>For example, if you have a custom HTML5 transformation type named "myhtml", then you may have a plug-in
extension that looks this:</p>
<codeblock outputclass="language-xml">&lt;!-- Simple variant: set properties and call default HTML5 -->
&lt;target name="dita2myhtml" depends="myhtml.init,dita2html5"/>
</codeblock>
<p>This type of extension is quite common, and is used to set default properties for your environment followed by
a normal build to use those properties. In this case, you'll need to replace <codeph>dita2html5</codeph> with
the normal HTML5 steps, swapping out <codeph>preprocess</codeph> for <codeph>preprocess2</codeph>:</p>
<codeblock
outputclass="language-xml normalize-space show-line-numbers show-whitespace"
>&lt;!-- Simple variant: set properties and call default HTML5 -->
&lt;target name="dita2myhtml"
depends="myhtml.init,
html5.init,
build-init,
<b>preprocess2,</b>
html5.topic,
html5.map,
html5.css"/></codeblock>
<note>If you use this simple method for customized PDF or HTML Help builds, you will automatically be using
<codeph>preprocess2</codeph>.</note>
<p>Some custom transformation types already require you to repeat the default dependencies, in which case you
should already call <codeph>preprocess</codeph> directly, as in the following:</p>
<codeblock
outputclass="language-xml normalize-space show-line-numbers show-whitespace"
>&lt;!-- More complex variant: add processing steps to default HTML5 -->
&lt;target name="dita2myhtml"
depends="myhtml.init,
build-init,
preprocess,
local-extensions-after-preprocess,
html5.topic,
html5.map,
html5.css"/></codeblock>
<p>In such cases, the modification is much easier – simply add a <codeph>2</codeph> to the existing
<codeph>preprocess</codeph> target.</p>
</section>
<section>
<title>How to test in a production environment</title>
<p>In some cases, you may be responsible for maintaining transformation types that are actually run by many people
on your team or around a company. In this case, you likely need to maintain your existing transformation types
based on the backwards-compatible <codeph>preprocess</codeph> modules, but also want to provide your colleagues
with a way to test their own documents using <codeph>preprocess2</codeph>.</p>
<p>There are several ways to do this. One fairly straightforward approach would be to create a new custom
transformation type that is exactly the same, except for preprocessing. For example, if you have a local HTML
variant called <codeph>myhtml</codeph> as above, instead of modifying that transformation directly, you could
create a second transformation type called <codeph>myhtml-beta</codeph> that provides exactly the same support,
but with the new map-first preprocessing:</p>
<codeblock outputclass="language-xml normalize-space show-line-numbers show-whitespace"><i
>&lt;!-- Original "myhtml" is not modified, used for production --></i>
&lt;target name="dita2myhtml5" depends="myhtml.init,dita2html5"/>
<i>&lt;!-- "myhtml-beta" used to test and provide feedback on preprocess2 --></i>
&lt;target name="dita2myhtml-beta"
depends="myhtml.init,
html5.init,
build-init,
<b>preprocess2,</b>
html5.topic,
html5.map,
html5.css"/></codeblock>
</section>
<section>
<title>Known limitations</title>
<p>The <codeph>preprocess2</codeph> implementation details are subject to change; dependencies within
<codeph>preprocess2</codeph> may be renamed or removed based on feedback.</p>
<p conkeyref="reusable-components/no-internal-preprocess2-ext"/>
</section>
</conbody>
</concept>

107
dita-ot-3.6/docsrc/reference/pdf-transform.dita Normal file
View file

@ -0,0 +1,107 @@
<?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="pdfdefault">
<title>PDF processing modules</title>
<shortdesc>The <option>PDF</option> (formerly known as <option>PDF2</option>) transformation process runs the
pre-processing routine and follows it by a series of additional targets. These steps work together to create a
merged set of content, convert the merged content to XSL-FO, and then format the XSL-FO file to PDF.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>DITAVAL
<indexterm>PDF</indexterm></indexterm>
<indexterm>Antenna House
<indexterm><codeph>transform.fo2pdf</codeph></indexterm>
<indexterm><filepath>topic.fo</filepath></indexterm></indexterm>
<indexterm>Apache FOP
<indexterm><codeph>transform.fo2pdf</codeph></indexterm>
<indexterm><filepath>topic.fo</filepath></indexterm></indexterm>
<indexterm>PDF
<indexterm>preprocessing</indexterm></indexterm>
<indexterm>targets
<indexterm>PDF</indexterm></indexterm>
<indexterm>XSLT
<indexterm>PDF</indexterm></indexterm>
<indexterm>RenderX
<indexterm><codeph>transform.fo2pdf</codeph></indexterm>
<indexterm><filepath>topic.fo</filepath></indexterm></indexterm>
<indexterm>XEP
<index-see>RenderX</index-see></indexterm>
<indexterm>index
<indexterm>PDF</indexterm></indexterm>
<indexterm><filepath>stage1.xml</filepath></indexterm>
<indexterm>pipelines
<indexterm>PDF</indexterm></indexterm>
<indexterm><filepath>topic.fo</filepath></indexterm>
<indexterm><filepath>stage1a.xml</filepath></indexterm>
<indexterm><filepath>stage2.fo</filepath></indexterm>
<indexterm><filepath>stage3.fo</filepath></indexterm>
<indexterm><filepath>topic.fo</filepath></indexterm>
</keywords>
</metadata>
</prolog>
<conbody>
<section>
<p>The PDF process includes many Ant targets. During a typical conversion from map to PDF, the following targets
are most significant.</p>
<dl>
<dlentry>
<dt><codeph>map2pdf2</codeph></dt>
<dd>Creates a merged file by calling a common Java merge module. It then calls the
<codeph>publish.map.pdf</codeph> target to do the remainder of the work.</dd>
</dlentry>
<dlentry>
<dt><codeph>publish.map.pdf</codeph></dt>
<dd>Performs some initialization and then calls the <codeph>transform.topic2pdf</codeph> target to do the
remainder of processing.</dd>
</dlentry>
<dlentry>
<dt><codeph>transform.topic2pdf</codeph></dt>
<dd>Converts the merged file to XSL-FO, generates the PDF, and deletes the <filepath>topic.fo</filepath> file,
unless instructed to keep it.</dd>
</dlentry>
</dl>
<p>The <codeph>transform.topic2pdf</codeph> target uses the following targets to perform those tasks:</p>
<dl>
<dlentry>
<dt><codeph>transform.topic2fo</codeph></dt>
<dd>Convert the merged file to an XSL-FO file. This process is composed of several sub-targets. </dd>
</dlentry>
<!-- Begin sub-targets -->
<dlentry>
<dt><codeph>transform.topic2fo.index</codeph></dt>
<dd>Runs a Java process to set up index processing, based on the document language. This step generates the
file <filepath>stage1.xml</filepath> in the temporary processing directory. </dd>
</dlentry>
<dlentry>
<dt><codeph>transform.topic2fo.flagging</codeph></dt>
<dd>Sets up preprocessing for flagging based on a DITAVAL file. This step generates the file
<filepath>stage1a.xml</filepath> in the temporary processing directory.</dd>
</dlentry>
<dlentry>
<dt><codeph>transform.topic2fo.main</codeph></dt>
<dd>Does the bulk of the conversion from DITA to XSL-FO. It runs the XSLT-based process that creates
<filepath>stage2.fo</filepath> in the temporary processing directory</dd>
</dlentry>
<dlentry>
<dt><codeph>transform.topic2fo.i18n</codeph></dt>
<dd>Does additional localization processing on the FO file; it runs a Java process that converts
<filepath>stage2.fo</filepath> into <filepath>stage3.fo</filepath>, followed by an XSLT process that
converts <filepath>stage3.fo</filepath> into <filepath>topic.fo</filepath>.</dd>
</dlentry>
<!-- End sub-targets -->
<dlentry>
<dt><codeph>transform.fo2pdf</codeph></dt>
<dd>Converts the <filepath>topic.fo</filepath> file into PDF using the specified FO processor (Antenna House,
XEP, or Apache FOP).</dd>
</dlentry>
<dlentry>
<dt><codeph>delete.fo2pdf.topic.fo</codeph></dt>
<dd>Deletes the <filepath>topic.fo</filepath> file, unless otherwise specified by setting an Ant property or
command-line option.</dd>
</dlentry>
</dl>
</section>
</conbody>
</concept>

59
dita-ot-3.6/docsrc/reference/pdf-transformation-history.dita Normal file
View file

@ -0,0 +1,59 @@
<?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="history-pdf-transformation">
<title>History of the PDF transformation</title>
<shortdesc>The DITA Open Toolkit PDF transformation was originally based on a third-party contribution by Idiom
Technologies, and is commonly known as the “pdf2” plug-in.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm><xmlelement>info</xmlelement></indexterm>
<indexterm>legacypdf</indexterm>
<indexterm>PDF2
<index-see>PDF
<indexterm>plug-in, history of</indexterm></index-see></indexterm>
<indexterm>languages
<indexterm>auto-generated strings</indexterm></indexterm>
<indexterm>PDF
<indexterm>plug-in, history of</indexterm>
<indexterm>HTML formatting differences</indexterm></indexterm>
<indexterm>Idiom Technologies</indexterm>
<indexterm>HTML
<indexterm>PDF formatting differences</indexterm></indexterm>
<indexterm>DITA 1.1</indexterm>
<indexterm>index
<indexterm>indexing domain</indexterm></indexterm>
<indexterm>Customization directory</indexterm>
<indexterm>org.dita.pdf2</indexterm>
</keywords>
</metadata>
</prolog>
<conbody>
<p>When IBM developed the code that later became DITA-OT, it included only a proof-of-concept PDF transformation.
IBM had their own processing chain for producing PDFs from SGML, which they had developed over several decades, so
resources were focused primarily on XHTML output and preprocessing.</p>
<p>Since the initial proof-of-concept transformation was not robust enough for production-grade output, companies
began to develop their own PDF transformations. One company, Idiom Technologies, made their transformation (known
as the “pdf2” transformation) available as open source on 23 February 2006. The Idiom plug-in was initially
available as a separately-downloadable plug-in that could be installed into DITA-OT.</p>
<p>Later the DITA-OT project formally incorporated the Idiom plug-in as a demonstration in the
<filepath>demo/fo</filepath> directory. Beginning with DITA-OT version 1.5, released 18 December 2009, the
“pdf2” code served as the main, supported PDF transformation. (The original PDF transformation was deprecated and
renamed “legacypdf”.) In DITA-OT version 1.6, the “pdf2” plug-in was moved to
<filepath>plugins/org.dita.pdf2</filepath>. </p>
<p>The fact that the current PDF transformation was not originally developed in parallel with the other core DITA-OT
transformations led to anomalies that often confuse users:</p>
<ul>
<li>Elements are often (by default) styled differently in the XHTML and PDF transformations. For example, consider
the <xmlelement>info</xmlelement> element in a task topic. In HTML output, this is an inline element; in PDF
output, it is a block-level element.</li>
<li>The auto-generated strings used for localization are different, and so languages that are supported by DITA-OT
differ based on whether the XHTML or PDF transformation is used.</li>
<li>The Idiom plug-in used its own extension mechanism (the <filepath>Customization</filepath> folder) to provide
overrides to the PDF transformation.</li>
<li>Before the release of DITA 1.1 (which added support for the indexing domain), Idiom developed an index
extension that used a FrameMaker-inspired syntax.</li>
</ul>
</conbody>
</concept>

24
dita-ot-3.6/docsrc/reference/preprocess-branch-filter.dita Normal file
View file

@ -0,0 +1,24 @@
<?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="preprocess-branch-filter">
<title>Branch filtering (branch-filter)</title>
<shortdesc>The <codeph>branch-filter</codeph> step filters topics using DITAVAL files defined in the map.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>DITAVAL
<indexterm><codeph>branch-filter</codeph> preprocess step</indexterm></indexterm>
<indexterm>filters
<index-see-also>branch filters</index-see-also>
<index-see-also>DITAVAL</index-see-also></indexterm>
<indexterm>profiling
<index-see-also>DITAVAL</index-see-also></indexterm>
<indexterm>branch filters</indexterm>
<indexterm>preprocessing
<indexterm><codeph>branch-filter</codeph></indexterm></indexterm>
<indexterm><codeph>branch-filter</codeph></indexterm>
</keywords>
</metadata>
</prolog>
</concept>

35
dita-ot-3.6/docsrc/reference/preprocess-chunk.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="preprocess-chunk">
<title>Chunk topics (chunk)</title>
<shortdesc>The <codeph>chunk</codeph> step breaks apart and assembles referenced DITA content based on the @chunk
attribute in maps. This step is implemented in Java.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm><xmlatt>chunk</xmlatt>
<indexterm>supported methods</indexterm></indexterm>
<indexterm>preprocessing
<indexterm><codeph>chunk</codeph></indexterm></indexterm>
<indexterm><codeph>chunk</codeph></indexterm>
<indexterm>Java
<indexterm>
<indexterm>chunk</indexterm></indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<conbody>
<p>DITA-OT has implemented processing for the following values of the <xmlatt>chunk</xmlatt> attribute:
<ul>
<li>select-topic</li>
<li>select-document</li>
<li>select-branch</li>
<li>by-topic</li>
<li>by-document</li>
<li>to-content</li>
<li>to-navigation</li>
</ul>
</p>
</conbody>
</concept>

17
dita-ot-3.6/docsrc/reference/preprocess-clean-map.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="preprocess-clean-map">
<title>Map cleanup (clean-map)</title>
<shortdesc>The <codeph>clean-map</codeph> step removes any elements and attributes that were added to files to support
preprocessing.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>preprocessing
<indexterm><codeph>clean-map</codeph></indexterm></indexterm>
<indexterm><codeph>clean-map</codeph></indexterm>
</keywords>
</metadata>
</prolog>
</concept>

74
dita-ot-3.6/docsrc/reference/preprocess-conref.dita Normal file
View file

@ -0,0 +1,74 @@
<?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="preprocess-conref">
<title>Resolve content references (conref)</title>
<shortdesc>The <codeph>conref</codeph> step resolves content references, processing only the DITA maps or topics that
use the <xmlatt>conref</xmlatt> attribute. This step is implemented in XSLT.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm><xmlelement>fig</xmlelement></indexterm>
<indexterm><xmlelement>xref</xmlelement></indexterm>
<indexterm><xmlelement>section</xmlelement></indexterm>
<indexterm><xmlatt>conref</xmlatt>
<indexterm>resolving</indexterm></indexterm>
<indexterm><xmlatt>id</xmlatt>
<indexterm><xmlatt>conref</xmlatt> resolution</indexterm></indexterm>
<indexterm><xmlatt>xref</xmlatt></indexterm>
<indexterm>preprocessing
<indexterm><codeph>conref</codeph></indexterm></indexterm>
<indexterm><codeph>conref</codeph></indexterm>
<indexterm>XSLT
<indexterm><codeph>conref</codeph> step</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<conbody>
<section>
<p>The values of the <xmlatt>id</xmlatt> attribute on referenced content are changed as the elements are pulled
into the new locations. This ensures that the values of the <xmlatt>id</xmlatt> attribute within the referencing
topic remain unique.</p>
<p>If an element is pulled into a new context along with a cross reference that references the target, both the
values of the <xmlatt>id</xmlatt> and <xmlatt>xref</xmlatt> attributes are updated so that they remain valid in
the new location. For example, a referenced topic might include a section as in the following example: <fig>
<title>Referenced topic that contains a section and cross reference</title>
<codeblock
outputclass="language-xml normalize-space show-line-numbers show-whitespace"
>&lt;topic id="referenced_topic">
&lt;title>...&lt;/title>
&lt;body>
&lt;section id="sect">
&lt;title>Sample section&lt;/title>
&lt;p>Figure &lt;xref href="#referenced_topic/fig"/>
contains a code sample that demonstrates ... .&lt;/p>
&lt;fig id="fig">
&lt;title>Code sample&lt;/title>
&lt;codeblock>....&lt;/codeblock>
&lt;/fig>
&lt;/section>
&lt;/body>
&lt;/topic></codeblock>
</fig></p>
<p>When the section is referenced using a <xmlatt>conref</xmlatt> attribute, the value of the <xmlatt>id</xmlatt>
attribute on the <xmlelement>fig</xmlelement> element is modified to ensure that it remains unique in the new
context. At the same time, the <xmlelement>xref</xmlelement> element is also modified so that it remains valid
as a local reference. For example, if the referencing topic has an <xmlatt>id</xmlatt> set to "new_topic", then
the conrefed element may look like this in the intermediate document <xmlelement>section</xmlelement>. <fig>
<title>Resolved conrefed <xmlelement>section</xmlelement> element after the conref step</title>
<codeblock outputclass="language-xml normalize-space show-line-numbers show-whitespace">&lt;section id="sect">
&lt;title>Sample section&lt;/title>
&lt;p>Figure &lt;xref href="#new_topic/d1e25"/> contains a code sample
that demonstrates ... .&lt;/p>
&lt;fig id="d1e25">
&lt;title>Code sample&lt;/title>
&lt;codeblock>....&lt;/codeblock>
&lt;/fig>
&lt;/section></codeblock>
</fig></p>
<p>In this case, the value of the <xmlatt>id</xmlatt> attribute on the <xmlelement>fig</xmlelement> element has
been changed to a generated value of "d1e25". At the same time, the <xmlelement>xref</xmlelement> element has
been updated to use that new generated ID, so that the cross reference remains valid.</p>
</section>
</conbody>
</concept>

19
dita-ot-3.6/docsrc/reference/preprocess-conrefpush.dita Normal file
View file

@ -0,0 +1,19 @@
<?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="preprocess-conrefpush">
<title>Conref push (conrefpush)</title>
<shortdesc>The <codeph>conrefpush</codeph> step resolves "conref push" references. This step only processes documents
that use conref push or that are updated due to the push action. This step is implemented in Java.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>preprocessing
<indexterm><codeph>conrefpush</codeph></indexterm></indexterm>
<indexterm><codeph>conrefpush</codeph></indexterm>
<indexterm>Java
<indexterm>conrefpush</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
</concept>

18
dita-ot-3.6/docsrc/reference/preprocess-copy-to.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="preprocess-copy-to">
<title>Copy topics (copy-to)</title>
<shortdesc>The <codeph>copy-to</codeph> step makes a copy of original topic resources to new resources defined by the
<xmlatt>copy-to</xmlatt> attribute.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm><xmlatt>copy-to</xmlatt></indexterm>
<indexterm>preprocessing
<indexterm><codeph>copy-to</codeph></indexterm></indexterm>
<indexterm><codeph>copy-to</codeph></indexterm>
</keywords>
</metadata>
</prolog>
</concept>

22
dita-ot-3.6/docsrc/reference/preprocess-copyfiles.dita Normal file
View file

@ -0,0 +1,22 @@
<?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="preprocess-copyfiles">
<title>Copy related files (copy-files)</title>
<shortdesc>The <codeph>copy-files</codeph> step copies non-DITA resources to the output directory, such as HTML files
that are referenced in a map or images that are referenced by a DITAVAL file. Which files are copied depends on the
transformation type.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>DITAVAL
<indexterm><codeph>copy-files</codeph> preprocess step</indexterm></indexterm>
<indexterm>preprocessing
<indexterm><codeph>copy-files</codeph></indexterm></indexterm>
<indexterm><codeph>copy-files</codeph></indexterm>
<indexterm>images
<indexterm>copying</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
</concept>

44
dita-ot-3.6/docsrc/reference/preprocess-debugfilter.dita Normal file
View file

@ -0,0 +1,44 @@
<?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="preprocess-debugfilter">
<title>Debug and filter (debug-filter)</title>
<shortdesc>The <codeph>debug-filter</codeph> step processes all referenced DITA content and creates copies in a
temporary directory. As the DITA content is copied, filtering is performed, debugging information is inserted, and
table column names are adjusted. This step is implemented in Java.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm><xmlelement>ph</xmlelement></indexterm>
<indexterm><xmlatt>xtrf</xmlatt></indexterm>
<indexterm><xmlatt>xtrc</xmlatt></indexterm>
<indexterm>DITAVAL
<indexterm><codeph>debug-filter</codeph> preprocess step</indexterm></indexterm>
<indexterm>preprocessing
<indexterm><codeph>debug-filter</codeph></indexterm></indexterm>
<indexterm><codeph>debug-filter</codeph></indexterm>
<indexterm>debugging
<indexterm><codeph>debug-filter</codeph> preprocess step</indexterm></indexterm>
<indexterm>tables
<indexterm>DITAVAL</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<conbody>
<section>
<p>The following modifications are made to the DITA source:</p>
<ul>
<li>If a DITAVAL file is specified, the DITA source is filtered according to the entries in the DITAVAL
file.</li>
<li>Debug information is inserted into each element using the <xmlatt>xtrf</xmlatt> and <xmlatt>xtrc</xmlatt>
attributes. The values of these attributes enable messages later in the build to reliably indicate the
original source of the error. For example, a message might trace back to the fifth <xmlelement>ph</xmlelement>
element in a specific DITA topic. Without these attributes, that count might no longer be available due to
filtering and other processing.</li>
<li>The table column names are adjusted to use a common naming scheme. This is done only to simplify later
conref processing. For example, if a table row is pulled into another table, this ensures that a reference to
"column 5 properties" will continue to work in the fifth column of the new table.</li>
</ul>
</section>
</conbody>
</concept>

269
dita-ot-3.6/docsrc/reference/preprocess-flagging.dita Normal file
View file

@ -0,0 +1,269 @@
<?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="flagging" rev="1.7">
<title>Flagging (flag-module)</title>
<shortdesc>Beginning with DITA-OT 1.7, flagging support is implemented as a common <codeph>flag-module</codeph>
preprocessing step. The module evaluates the DITAVAL against all flagging attributes, and adds DITA-OT–specific
hints to the topic when flags are active. Any extended transformation type may use these hints to support flagging
without adding logic to interpret the DITAVAL.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm><xmlelement>foreign</xmlelement></indexterm>
<indexterm><xmlelement>ditaval-startprop</xmlelement></indexterm>
<indexterm><xmlelement>prop</xmlelement></indexterm>
<indexterm><xmlelement>revprop</xmlelement></indexterm>
<indexterm><xmlelement>startflag</xmlelement></indexterm>
<indexterm><xmlelement>endflag</xmlelement></indexterm>
<indexterm><xmlelement>ditaval-endprop</xmlelement></indexterm>
<indexterm><xmlelement>ditaval-prop</xmlelement></indexterm>
<indexterm><xmlelement>p</xmlelement></indexterm>
<indexterm><xmlelement>ol</xmlelement></indexterm>
<indexterm><xmlelement>li</xmlelement></indexterm>
<indexterm><xmlatt>outputclass</xmlatt></indexterm>
<indexterm><xmlatt>xtrf</xmlatt></indexterm>
<indexterm><xmlatt>xtrc</xmlatt></indexterm>
<indexterm><xmlatt>outputclass</xmlatt></indexterm>
<indexterm><xmlatt>rev</xmlatt></indexterm>
<indexterm>DITAVAL
<indexterm><codeph>flag-module</codeph> preprocess step</indexterm></indexterm>
<indexterm>DITA
<indexterm>specializations</indexterm></indexterm>
<indexterm>preprocessing
<indexterm><codeph>flag-module</codeph></indexterm></indexterm>
<indexterm><codeph>flag-module</codeph></indexterm>
<indexterm>flagging</indexterm>
<indexterm>XSLT
<indexterm><codeph>flag-module</codeph> preprocess step</indexterm></indexterm>
<indexterm>CSS
<indexterm><xmlatt>outputclass</xmlatt></indexterm></indexterm>
<indexterm>images
<indexterm>flagging</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<refbody>
<section>
<title>Evaluating the DITAVAL flags</title>
<p>Flagging is implemented as a reusable module during the preprocess stage. If a DITAVAL file is not used with a
build, this step is skipped with no change to the file.</p>
<p>When a flag is active, relevant sections of the DITAVAL itself are copied into the topic as a sub-element of
the current topic. The active flags are enclosed in a pseudo-specialization of the
<xmlelement>foreign</xmlelement> element (referred to as a pseudo-specialization because it is used only under
the covers, with all topic types; it is not integrated into any shipped document types).</p>
<parml>
<plentry>
<pt><xmlelement>ditaval-startprop</xmlelement></pt>
<pd>
<p>When any flag is active on an element, a <xmlelement>ditaval-startprop</xmlelement> element will be
created as the first child of the flagged element:</p>
<codeblock
outputclass="language-xml"
>&lt;ditaval-startprop class="+ topic/foreign ditaot-d/ditaval-startprop "></codeblock>
<p>The <xmlelement>ditaval-startprop</xmlelement> element will contain the following:
<ul>
<li>If the active flags should create a new style, that style is included using standard CSS markup on
the <xmlatt>outputclass</xmlatt> attribute. Output types that make use of CSS, such as XHTML, can use
this value as-is.</li>
<li>If styles conflict, and a <xmlelement>style-conflict</xmlelement> element exists in the DITAVAL, it
will be copied as a child of <xmlelement>ditaval-startprop</xmlelement>.</li>
<li>Any <xmlelement>prop</xmlelement> or <xmlelement>revprop</xmlelement> elements that define active
flags will be copied in as children of the <xmlelement>ditaval-startprop</xmlelement> element. Any
<xmlelement>startflag</xmlelement> children of the properties will be included, but
<xmlelement>endflag</xmlelement> children will not.</li>
</ul>
</p>
</pd>
</plentry>
<plentry>
<pt><xmlelement>ditaval-endprop</xmlelement></pt>
<pd>
<p>When any flag is active on an element, a <xmlelement>ditaval-endprop</xmlelement> element will be created
as the last child of the flagged element:</p>
<codeblock
outputclass="language-xml"
>&lt;ditaval-endprop class="+ topic/foreign ditaot-d/ditaval-endprop "></codeblock>
<p>CSS values and <xmlelement>style-conflict</xmlelement> elements are not included on this element.</p>
<p>Any <xmlelement>prop</xmlelement> or <xmlelement>revprop</xmlelement> elements that define active flags
will be copied in as children of <xmlelement>ditaval-prop</xmlelement>. Any
<xmlelement>startflag</xmlelement> children of the properties will be included, but
<xmlelement>endflag</xmlelement> children will not.</p>
</pd>
</plentry>
</parml>
</section>
<section>
<title>Supporting flags in overrides or custom transformation types</title>
<p>For most transformation types, the <xmlelement>foreign</xmlelement> element should be ignored by default,
because arbitrary non-DITA content may not mix well unless coded for ahead of time. If the
<xmlelement>foreign</xmlelement> element is ignored by default, or if a rule is added to specifically ignore
<xmlelement>ditaval-startprop</xmlelement> and <xmlelement>ditaval-endprop</xmlelement>, then the added
elements will have no impact on a transform. If desired, flagging support may be integrated at any time in the
future.</p>
<p>The processing described above runs as part of the common preprocess, so any transform that uses the default
preprocess will get the topic updates. To support generating flags as images, XSLT based transforms can use
default fallthrough processing in most cases. For example, if a paragraph is flagged, the first child of
<xmlelement>p</xmlelement> will contain the start flag information; adding a rule to handle images in
<xmlelement>ditaval-startprop</xmlelement> will cause the image to appear at the start of the paragraph
content.</p>
<p>In some cases fallthrough processing will not result in valid output; for those cases, the flags must be
explicitly processed. This is done in the XHTML transform for elements like <xmlelement>ol</xmlelement>, because
fallthrough processing would place images in between <xmlelement>ol</xmlelement> and
<xmlelement>li</xmlelement>. To handle this, the code processes <xmlelement>ditaval-startprop</xmlelement>
before starting the element, and <xmlelement>ditaval-endprop</xmlelement> at the end. Fallthrough processing is
then disabled for those elements as children of <xmlelement>ol</xmlelement>.</p></section>
<example>
<title>Example DITAVAL</title>
<p>Assume the following DITAVAL file is in use during a build. This DITAVAL will be used for each of the following
content examples.</p>
<codeblock
outputclass="language-xml normalize-space show-line-numbers show-whitespace"
>&lt;?xml version="1.0" encoding="UTF-8"?>
&lt;val>
<i>&lt;!-- Define what happens in the case of conflicting styles --></i>
&lt;style-conflict background-conflict-color="red"/>
<i>&lt;!-- Define two flagging properties that give styles (no image) --></i>
&lt;prop action="flag" att="audience" style="underline" val="user"
backcolor="green"/>
&lt;prop action="flag" att="platform" style="overline" val="win"
backcolor="blue"/>
<i>&lt;!-- Define a property that includes start and end image flags --></i>
&lt;prop action="flag" att="platform" val="linux" style="overline"
backcolor="blue">
&lt;startflag imageref="startlin.png">
&lt;alt-text>Start linux&lt;/alt-text>&lt;/startflag>
&lt;endflag imageref="endlin.png">
&lt;alt-text>End linux&lt;/alt-text>&lt;/endflag>
&lt;/prop>
<i>&lt;!-- Define a revision that includes start and end image flags --></i>
&lt;revprop action="flag" style="double-underline" val="rev2">
&lt;startflag imageref="start_rev.gif">
&lt;alt-text>START&lt;/alt-text>&lt;/startflag>
&lt;endflag imageref="end_rev.gif">&lt;alt-text>END&lt;/alt-text>&lt;/endflag>
&lt;/revprop>
&lt;/val></codeblock>
</example>
<example>
<title>Content example 1: Adding style</title>
<p>Now assume the following paragraph exists in a topic. Class attributes are included, as they would normally be
in the middle of the preprocess routine; <xmlatt>xtrf</xmlatt> and <xmlatt>xtrc</xmlatt> are left off for
clarity.</p>
<codeblock
outputclass="language-xml"
>&lt;p audience="user">Simple user; includes style but no images&lt;/p></codeblock>
<p>Based on the DITAVAL above, audience="user" results in a style with underlining and with a green background.
The interpreted CSS value is added to <xmlatt>outputclass</xmlatt> on
<xmlelement>ditaval-startprop</xmlelement>, and the actual property definition is included at the start and end
of the element. The output from the flagging step looks like this (with newlines added for clarity, and class
attributes added as they would appear in the temporary file):</p>
<p>The resulting file after the flagging step looks like this; for clarity, newlines are added, while
<xmlatt>xtrf</xmlatt> and <xmlatt>xtrc</xmlatt> are removed:</p>
<codeblock
outputclass="language-xml normalize-space show-line-numbers show-whitespace"
>&lt;p audience="user" class="- topic/p ">
<b>&lt;ditaval-startprop</b>
<b>class="+ topic/foreign ditaot-d/ditaval-startprop "</b>
<b>outputclass="background-color:green;text-decoration:underline;"></b>
<b>&lt;prop action="flag" att="audience" style="underline" val="user"
backcolor="green"/></b>
<b>&lt;/ditaval-startprop></b>
Simple user; includes style but no images
<b>&lt;ditaval-endprop</b>
<b>class="+ topic/foreign ditaot-d/ditaval-endprop "></b>
<b>&lt;prop action="flag" att="audience" style="underline" val="user"
backcolor="green"/></b>
<b>&lt;/ditaval-endprop></b>
&lt;/p></codeblock>
</example>
<example>
<title>Content example 2: Conflicting styles</title>
<p>This example includes a paragraph with conflicting styles. When the audience and platform attributes are both
evaluated, the DITAVAL indicates that the background color is both green and blue. In this situation, the
<xmlelement>style-conflict</xmlelement> element is evaluated to determine how to style the content.</p>
<codeblock
outputclass="language-xml"
>&lt;p audience="user" platform="win">Conflicting styles (still no images)&lt;/p></codeblock>
<p>The <xmlelement>style-conflict</xmlelement> element results in a background color of red, so this value is
added to <xmlatt>outputclass</xmlatt> on <xmlelement>ditaval-startprop</xmlelement>. As above, active properties
are copied into the generated elements; the <xmlelement>style-conflict</xmlelement> element itself is also
copied into the generated <xmlelement>ditaval-startprop</xmlelement> element.</p>
<p>The resulting file after the flagging step looks like this; for clarity, newlines are added, while
<xmlatt>xtrf</xmlatt> and <xmlatt>xtrc</xmlatt> are removed:</p>
<codeblock
outputclass="language-xml normalize-space show-line-numbers show-whitespace"
>&lt;p audience="user" platform="win" class="- topic/p ">
<b>&lt;ditaval-startprop</b>
<b>class="+ topic/foreign ditaot-d/ditaval-startprop "</b>
<b>outputclass="background-color:red;"></b>
<b>&lt;style-conflict background-conflict-color="red"/></b>
<b>&lt;prop action="flag" att="audience" style="underline" val="user"
backcolor="green"/></b>
<b>&lt;prop action="flag" att="platform" style="overline" val="win"
backcolor="blue"/></b>
<b>&lt;/ditaval-startprop></b>
Conflicting styles (still no images)
<b>&lt;ditaval-endprop</b>
<b>class="+ topic/foreign ditaot-d/ditaval-endprop "></b>
<b>&lt;prop action="flag" att="platform" style="overline" val="win"
backcolor="blue"/></b>
<b>&lt;prop action="flag" att="audience" style="underline" val="user"
backcolor="green"/></b><b>
&lt;/ditaval-endprop></b>
&lt;/p></codeblock>
</example>
<example>
<title>Content example 3: Adding image flags</title>
<p>This example includes image flags for both <xmlatt>platform</xmlatt> and <xmlatt>rev</xmlatt>, which are
defined in DITAVAL <xmlelement>prop</xmlelement> and <xmlelement>revprop</xmlelement> elements.</p>
<codeblock
outputclass="language-xml normalize-space show-line-numbers show-whitespace"
>&lt;ol platform="linux" rev="rev2">
&lt;li>Generate images for platform="linux" and rev="2"&lt;/li>
&lt;/ol></codeblock>
<p>As above, the <xmlelement>ditaval-startprop</xmlelement> and <xmlelement>ditaval-endprop</xmlelement> nest the
active property definitions, with the calculated CSS value on <xmlatt>outputclass</xmlatt>. The
<xmlelement>ditaval-startprop</xmlelement> drops the ending image, and
<xmlelement>ditaval-endprop</xmlelement> drops the starting image. To make document-order processing more
consistent, property flags are always included before revisions in <xmlelement>ditaval-startprop</xmlelement>,
and the order is reversed for <xmlelement>ditaval-endprop</xmlelement>.</p>
<p>The resulting file after the flagging step looks like this; for clarity, newlines are added, while
<xmlatt>xtrf</xmlatt> and <xmlatt>xtrc</xmlatt> are removed:</p>
<codeblock
outputclass="language-xml normalize-space show-line-numbers show-whitespace"
>&lt;ol platform="linux" rev="rev2" class="- topic/ol ">
<b>&lt;ditaval-startprop</b>
<b>class="+ topic/foreign ditaot-d/ditaval-startprop "</b>
<b>outputclass="background-color:blue;</b>
<b>text-decoration:underline;</b>
<b>text-decoration:overline;"></b>
<b>&lt;prop action="flag" att="platform" val="linux" style="overline"
backcolor="blue"></b>
<b>&lt;startflag imageref="startlin.png"></b>
<b>&lt;alt-text>Start linux&lt;/alt-text>&lt;/startflag>&lt;/prop></b>
<b>&lt;revprop action="flag" style="double-underline" val="rev2"></b>
<b>&lt;startflag imageref="start_rev.gif"></b>
<b>&lt;alt-text> &lt;/alt-text>&lt;/startflag>&lt;/revprop></b>
<b>&lt;/ditaval-startprop></b>
&lt;li class="- topic/li ">
Generate images for platform="linux" and rev="2"
&lt;/li>
<b>&lt;ditaval-endprop</b>
<b>class="+ topic/foreign ditaot-d/ditaval-endprop "></b>
<b>&lt;revprop action="flag" style="double-underline" val="rev2"></b>
<b>&lt;endflag imageref="end_rev.gif"></b>
<b>&lt;alt-text>END&lt;/alt-text>&lt;/endflag>&lt;/revprop></b>
<b>&lt;prop action="flag" att="platform" val="linux" style="overline"</b>
<b>backcolor="blue"></b>
<b>&lt;endflag imageref="endlin.png"></b>
<b>&lt;alt-text>End linux&lt;/alt-text>&lt;/endflag>&lt;/prop></b>
<b>&lt;/ditaval-endprop></b>
&lt;/ol></codeblock>
</example>
</refbody>
</reference>

180
dita-ot-3.6/docsrc/reference/preprocess-genlist.dita Normal file
View file

@ -0,0 +1,180 @@
<?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="preprocess-genlist">
<title>Generate lists (gen-list)</title>
<shortdesc>The <codeph>gen-list</codeph> step examines the input files and creates lists of topics, images, document
properties, or other content. These lists are used by later steps in the pipeline. This step is implemented in
Java.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>deprecated features
<indexterm><parmname>htmlfile</parmname></indexterm></indexterm>
<indexterm>deprecated features
<indexterm><codeph>html.file</codeph></indexterm></indexterm>
<indexterm>deprecated features
<indexterm><parmname>imagefile</parmname></indexterm></indexterm>
<indexterm>deprecated features
<indexterm><codeph>image.file</codeph></indexterm></indexterm>
<indexterm>preprocessing
<indexterm><codeph>gen-list</codeph></indexterm></indexterm>
<indexterm><codeph>gen-list</codeph></indexterm>
<indexterm>conref</indexterm>
<indexterm>dita.list</indexterm>
<indexterm>dita.xml.properties</indexterm>
</keywords>
</metadata>
</prolog>
<refbody>
<section>
<p>For example, one list includes all topics that make use of the conref attribute; only those files are processed
during the conref stage of the build. The list file name name is derived from the list file property. For
example, the <codeph>conref.list</codeph> file is generated for “conreffile” and a corresponding list property
is provided for each generated list, in this case “conreflist”.</p>
<p>The result of this step is a set of several list files in the temporary directory, including
<filepath>dita.list</filepath> and <filepath>dita.xml.properties</filepath>.</p>
<table outputclass="table-hover" frame="none" colsep="0" rowsep="1">
<tgroup cols="3">
<colspec colwidth="2*"/>
<colspec colwidth="3*"/>
<colspec colwidth="3*"/>
<thead>
<row>
<entry>List file property</entry>
<entry>List file</entry>
<entry>Usage</entry>
</row>
</thead>
<tbody>
<row>
<entry>canditopicsfile</entry>
<entry><codeph>canditopics.list</codeph>
<indexterm>canditopics.list</indexterm></entry>
<entry/>
</row>
<row>
<entry>conreffile</entry>
<entry><codeph>conref.list</codeph>
<indexterm>conref.list</indexterm></entry>
<entry>Documents that contain conref attributes that need to be resolved in preprocess.</entry>
</row>
<row>
<entry>conreftargetsfile</entry>
<entry><codeph>conreftargets.list</codeph>
<indexterm>conreftargets.list</indexterm></entry>
<entry/>
</row>
<row>
<entry>copytosourcefile</entry>
<entry><codeph>copytosource.list</codeph>
<indexterm>copytosource.list</indexterm></entry>
<entry/>
</row>
<row>
<entry>flagimagefile</entry>
<entry><codeph>flagimage.list</codeph>
<indexterm>flagimage.list</indexterm></entry>
<entry/>
</row>
<row>
<entry>fullditamapandtopicfile</entry>
<entry><codeph>fullditamapandtopic.list</codeph>
<indexterm>fullditamapandtopic.list</indexterm></entry>
<entry>All of the ditamap and topic files that are referenced during the transformation. These may be
referenced by href or conref attributes.</entry>
</row>
<row>
<entry>fullditamapfile</entry>
<entry><codeph>fullditamap.list</codeph>
<indexterm>fullditamap.list</indexterm></entry>
<entry>All of the ditamap files in dita.list</entry>
</row>
<row>
<entry>fullditatopicfile</entry>
<entry><codeph>fullditatopic.list</codeph>
<indexterm>fullditatopic.list</indexterm></entry>
<entry>All of the topic files in dita.list</entry>
</row>
<row>
<entry>hrefditatopicfile</entry>
<entry><codeph>hrefditatopic.list</codeph>
<indexterm>hrefditatopic.list</indexterm></entry>
<entry>All of the topic files that are referenced with an href attribute</entry>
</row>
<row>
<entry>hreftargetsfile</entry>
<entry><codeph>hreftargets.list</codeph>
<indexterm>hreftargets.list</indexterm></entry>
<entry>Link targets</entry>
</row>
<row importance="deprecated">
<entry>htmlfile</entry>
<entry><codeph>html.list</codeph>
<indexterm>html.list</indexterm></entry>
<entry>Resource files</entry>
</row>
<row importance="deprecated">
<entry>imagefile</entry>
<entry><codeph>image.list</codeph>
<indexterm>image.list</indexterm></entry>
<entry>Image files that are referenced in the content</entry>
</row>
<row>
<entry>outditafilesfile</entry>
<entry><codeph>outditafiles.list</codeph>
<indexterm>outditafiles.list</indexterm></entry>
<entry/>
</row>
<row>
<entry>resourceonlyfile</entry>
<entry><codeph>resourceonly.list</codeph>
<indexterm>resourceonly.list</indexterm></entry>
<entry/>
</row>
<row>
<entry>subjectschemefile</entry>
<entry><codeph>subjectscheme.list</codeph>
<indexterm>subjectscheme.list</indexterm></entry>
<entry/>
</row>
<row>
<entry>subtargetsfile</entry>
<entry><codeph>subtargets.list</codeph>
<indexterm>subtargets.list</indexterm></entry>
<entry/>
</row>
<row>
<entry>tempdirToinputmapdir.relative.value</entry>
<entry/>
<entry/>
</row>
<row>
<entry>uplevels</entry>
<entry/>
<entry/>
</row>
<row>
<entry>user.input.dir
<indexterm>user.input.dir</indexterm></entry>
<entry/>
<entry>Absolute input directory path</entry>
</row>
<row>
<entry>user.input.file.listfile
<indexterm>user.input.file.listfile</indexterm></entry>
<entry/>
<entry>Input file list file</entry>
</row>
<row>
<entry>user.input.file
<indexterm>user.input.file</indexterm></entry>
<entry/>
<entry>Input file path, relative to the input directory</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
</refbody>
</reference>

20
dita-ot-3.6/docsrc/reference/preprocess-keyref.dita Normal file
View file

@ -0,0 +1,20 @@
<?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="preprocess-keyref">
<title>Resolve key references (keyref)</title>
<shortdesc>The <codeph>keyref</codeph> step examines all the keys that are defined in the DITA source and resolves the
key references. Links that make use of keys are updated so that any <xmlatt>href </xmlatt>value is replaced by the
appropriate target; key-based text replacement is also performed, and the key definition list file is written to the
temporary directory. This step is implemented in Java.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm><xmlatt>href</xmlatt></indexterm>
<indexterm>preprocessing
<indexterm><codeph>keyref</codeph></indexterm></indexterm>
<indexterm><codeph>keyref</codeph></indexterm>
</keywords>
</metadata>
</prolog>
</concept>

33
dita-ot-3.6/docsrc/reference/preprocess-maplink.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="preprocess-maplink">
<title>Map based linking (maplink)</title>
<shortdesc>This step collects links based on a map and moves those links into the referenced topics. The links are
created based on hierarchy in the DITA map, the <xmlatt>collection-type</xmlatt> attribute, and relationship tables.
This step is implemented in XSLT and Java.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm><xmlatt>collection-type</xmlatt></indexterm>
<indexterm>preprocessing
<indexterm><codeph>maplink</codeph></indexterm></indexterm>
<indexterm><codeph>maplink</codeph></indexterm>
<indexterm>Java
<indexterm>maplink</indexterm></indexterm>
<indexterm>XSLT
<indexterm><codeph>maplink</codeph> preprocessing step</indexterm></indexterm>
<indexterm>relationship tables
<indexterm><codeph>maplink</codeph> preprocessing step</indexterm></indexterm>
<indexterm>memory</indexterm>
</keywords>
</metadata>
</prolog>
<conbody>
<section>
<p>The <codeph>maplink</codeph> module runs an XSLT stylesheet that evaluates the map; it places all the generated
links into a single file in memory. The module then runs a Java program that pushes the generated links into the
applicable topics.</p>
</section>
</conbody>
</concept>

33
dita-ot-3.6/docsrc/reference/preprocess-mapref.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="preprocess-mapref">
<title>Resolve map references (mapref)</title>
<shortdesc>The <codeph>mapref</codeph> step resolves references from one DITA map to another. This step is implemented
in XSLT.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm><xmlelement>map</xmlelement></indexterm>
<indexterm>preprocessing
<indexterm><codeph>mapref</codeph></indexterm></indexterm>
<indexterm><codeph>mapref</codeph></indexterm>
<indexterm>XSLT
<indexterm><codeph>mapref</codeph> preprocessing step</indexterm></indexterm>
<indexterm>relationship tables
<indexterm><codeph>mapref</codeph> preprocessing step</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<conbody>
<section>
<p>Maps reference other maps by using the following sorts of markup:
<codeblock outputclass="language-xml">&lt;topicref href="other.ditamap" format="ditamap"/>
...
&lt;mapref href="other.ditamap"/></codeblock></p>
<p>As a result of the mapref step, the element that references another map is replaced by the topic references
from the other map. Relationship tables are pulled into the referencing map as a child of the root element
(<xmlelement>map</xmlelement> or a specialization of <xmlelement>map</xmlelement>). </p>
</section>
</conbody>
</concept>

62
dita-ot-3.6/docsrc/reference/preprocess-metadata.dita Normal file
View file

@ -0,0 +1,62 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "referenceconcept.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
<concept id="preprocess-metadata">
<title>Move metadata (move-meta-entries) and pull content into maps (mappull) </title>
<shortdesc>The <codeph>move-meta-entries</codeph> step pushes metadata back and forth between maps and topics. For
example, index entries and copyrights in the map are pushed into affected topics, so that the topics can be
processed later in isolation while retaining all relevant metadata. This step is implemented in Java.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm><xmlelement>topicref</xmlelement></indexterm>
<indexterm><xmlelement>linktext</xmlelement></indexterm>
<indexterm><xmlelement>shortdesc</xmlelement></indexterm>
<indexterm><xmlatt>locktitle</xmlatt></indexterm>
<indexterm><xmlatt>type</xmlatt></indexterm>
<indexterm><xmlatt>toc</xmlatt></indexterm>
<indexterm><xmlatt>print</xmlatt></indexterm>
<indexterm>preprocessing
<indexterm><codeph>move-meta-entries</codeph></indexterm></indexterm>
<indexterm><codeph>move-meta-entries</codeph></indexterm>
<indexterm>Java
<indexterm>move-meta-entries</indexterm></indexterm>
<indexterm>metadata
<indexterm>moving</indexterm></indexterm>
<indexterm>XSLT
<indexterm><codeph>move-meta-entries</codeph></indexterm></indexterm>
<indexterm>index
<indexterm>entries in map file</indexterm></indexterm>
<indexterm>TOC
<index-see>table of contents</index-see></indexterm>
</keywords>
</metadata>
</prolog>
<conbody>
<note>As of DITA-OT 2.2, the <codeph>move-meta-entries</codeph> and <codeph>mappull</codeph> steps have been merged.
The <codeph>mappull</codeph> step has been moved into <codeph>move-meta-entries</codeph>.</note>
<section>
<p>The <codeph>mappull</codeph> step pulls content from referenced topics into maps, and then cascades data within
maps. This step is implemented in XSLT.</p>
<p>The <codeph>mappull</codeph> step makes the following changes to the DITA map:
<ul>
<li>Titles are pulled from referenced DITA topics. Unless the <xmlatt>locktitle</xmlatt> attribute is set to
"yes", the pulled titles replace the navigation titles specified on the <xmlelement>topicref</xmlelement>
elements.</li>
<li>The <xmlelement>linktext</xmlelement> element is set based on the title of the referenced topic, unless it
is already specified locally.</li>
<li>The <xmlelement>shortdesc</xmlelement> element is set based on the short description of the referenced
topic, unless it is already specified locally.</li>
<li>The <xmlatt>type</xmlatt> attribute is set on <xmlelement>topicref</xmlelement> elements that reference
local DITA topics. The value of the <xmlatt>type</xmlatt> attribute is set to value of the root element of
the topic; for example, a <xmlelement>topicref</xmlelement> element that references a task topic is given a
<xmlatt>type</xmlatt> attribute set to "task"".</li>
<li>Attributes that cascade, such as <xmlatt>toc</xmlatt> and <xmlatt>print</xmlatt>, are made explicit on any
child <xmlelement>topicref</xmlelement> elements. This allows future steps to work with the attributes
directly, without reevaluating the cascading behavior.</li>
</ul>
</p>
</section>
</conbody>
</concept>

21
dita-ot-3.6/docsrc/reference/preprocess-profile.dita Normal file
View file

@ -0,0 +1,21 @@
<?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="preprocess-profile">
<title>Filter conditional content (profile)</title>
<shortdesc>The <codeph>profile</codeph> step removes content from topics and maps based on the rules in DITAVAL files
or the <xmlatt>print</xmlatt> attribute setting. Output can differ based on when filtering is done.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm><xmlatt>print</xmlatt></indexterm>
<indexterm>DITAVAL
<indexterm><codeph>profile</codeph> preprocess step</indexterm></indexterm>
<indexterm>profiling</indexterm>
<indexterm>preprocessing
<indexterm><codeph>profile</codeph></indexterm></indexterm>
<indexterm><codeph>profile</codeph></indexterm>
</keywords>
</metadata>
</prolog>
</concept>

31
dita-ot-3.6/docsrc/reference/preprocess-topic-fragment.dita Normal file
View file

@ -0,0 +1,31 @@
<?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="preprocess-topic-fragment">
<title>Resolve topic fragments and code references (topic-fragment)</title>
<shortdesc>The <codeph>topic-fragment</codeph> step expands content references to elements in the same topic and
resolves references made with the <xmlelement>coderef</xmlelement> element. This step is implemented in SAX
pipes.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm><xmlelement>coderef</xmlelement></indexterm>
<indexterm><xmlelement>codeblock</xmlelement></indexterm>
<indexterm>preprocessing
<indexterm><codeph>topic-fragment</codeph></indexterm></indexterm>
<indexterm><codeph>topic-fragment</codeph></indexterm>
<indexterm>Saxon</indexterm>
<indexterm>conref</indexterm>
</keywords>
</metadata>
</prolog>
<conbody>
<section>
<p>Content references to elements in the same topic are defined via same-topic fragments such as
<codeph>#./ID</codeph> in URIs.</p>
<p>The <xmlelement>coderef</xmlelement> element is used to reference code stored externally in non-XML documents.
During the pre-processing step, the referenced content is pulled into the containing
<xmlelement>codeblock</xmlelement> element.</p>
</section>
</conbody>
</concept>

37
dita-ot-3.6/docsrc/reference/preprocess-topicpull.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="preprocess-topicpull">
<title>Pull content into topics (topicpull)</title>
<shortdesc>The <codeph>topicpull</codeph> step pulls content into <xmlelement>xref</xmlelement> and
<xmlelement>link</xmlelement> elements. This step is implemented in XSLT.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm><xmlelement>xref</xmlelement></indexterm>
<indexterm><xmlelement>link</xmlelement></indexterm>
<indexterm><xmlelement>desc</xmlelement></indexterm>
<indexterm><xmlelement>linktext</xmlelement></indexterm>
<indexterm>preprocessing
<indexterm><codeph>topicpull</codeph></indexterm></indexterm>
<indexterm><codeph>topicpull</codeph></indexterm>
<indexterm>XSLT
<indexterm><codeph>topicpull</codeph></indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<conbody>
<section>
<p>If an <xmlelement>xref</xmlelement> element does not contain link text, the target is examined and the link
text is pulled. For example, a reference to a topic pulls the title of the topic; a reference to a list item
pulls the number of the item. If the <xmlelement>xref</xmlelement> element references a topic that has a short
description, and the <xmlelement>xref</xmlelement> element does not already contain a child
<xmlelement>desc</xmlelement> element, a <xmlelement>desc</xmlelement> element is created that contains the
text from the topic short description.</p>
<p>The process is similar for <xmlelement>link</xmlelement> elements. If the <xmlelement>link</xmlelement> element
does not have a child <xmlelement>linktext</xmlelement> element, one is created with the appropriate link text.
Similarly, if the <xmlelement>link</xmlelement> element does not have a child <xmlelement>desc</xmlelement>
element, and the short description of the target can be determined, a <xmlelement>desc</xmlelement> element is
created that contains the text from the topic short description.</p></section>
</conbody>
</concept>

17
dita-ot-3.6/docsrc/reference/preprocessing.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="preprocessarch">
<title>Pre-processing modules</title>
<shortdesc>The pre-processing operation is a set of steps that typically runs at the beginning of every DITA-OT
transformation. Each step or stage corresponds to an Ant target in the build pipeline; the
<codeph>preprocess</codeph> target calls the entire set of steps.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>preprocessing
<indexterm>modules</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
</concept>

62
dita-ot-3.6/docsrc/reference/processing-order.dita Normal file
View file

@ -0,0 +1,62 @@
<?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="processing-order">
<title>Processing order</title>
<shortdesc>The order of processing is often significant when evaluating DITA content. Although the DITA specification
does not mandate a specific order for processing, DITA-OT has determined that performing filtering before conref
resolution best meets user expectations. Switching the order of processing, while legal, may give different
results.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm><xmlelement>note</xmlelement></indexterm>
<indexterm><xmlatt>product</xmlatt></indexterm>
<indexterm><xmlatt>conref</xmlatt>
<indexterm>resolving</indexterm></indexterm>
<indexterm>filters
<indexterm>processing order</indexterm></indexterm>
<indexterm>processing</indexterm>
<indexterm>pipelines
<indexterm>processing order</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<conbody>
<section>
<p>The DITA-OT project has found that filtering first provides several benefits. Consider the following sample
that contains a <xmlelement>note</xmlelement> element that both uses conref and contains a
<xmlatt>product</xmlatt>
attribute:<codeblock
outputclass="language-xml"
>&lt;note conref="documentA.dita#doc/note" product="MyProd"/></codeblock></p>
<p>If the <xmlatt>conref</xmlatt> attribute is evaluated first, then documentA must be parsed in order to retrieve
the note content. That content is then stored in the current document (or in a representation of that document
in memory). However, if all content with product="MyProd" is filtered out, then that work is all discarded later
in the build.</p>
<p>If the filtering is done first (as in DITA-OT), this element is discarded immediately, and documentA is never
examined. This provides several important benefits:
<ul>
<li>Time is saved by discarding unused content as early as possible; all future steps can load the document
without this extra content.</li>
<li>Additional time is saved case by not evaluating the <xmlatt>conref</xmlatt> attribute; in fact, documentA
does not even need to be parsed.</li>
<li>Any user reproducing this build does not need documentA. If the content is sent to a translation team,
that team can reproduce an error-free build without documentA; this means documentA can be kept back from
translation, preventing accidental translation and increased costs.</li>
</ul></p>
<p>If the order of these two steps is reversed, so that conref is evaluated first, it is possible that results
will differ. For example, in the code sample above, the <xmlatt>product</xmlatt> attribute on the reference
target will override the product setting on the referencing note. Assume that the referenced
<xmlelement>note</xmlelement> element in documentA is defined as follows:
<codeblock
outputclass="language-xml"
>&lt;note id="note" product="SomeOtherProduct">This is an important note!&lt;/note></codeblock></p>
<p>A process that filters out product="SomeOtherProduct" will remove the target of the original conref before that
conref is ever evaluated, which will result in a broken reference. Evaluating conref first would resolve the
reference, and only later filter out the target of the conref. While some use cases can be found where this is
the desired behavior, benefits such as those described above resulted in the current processing order used by
DITA-OT.</p>
</section>
</conbody>
</concept>

62
dita-ot-3.6/docsrc/reference/processing-pipeline-modules.dita Normal file
View file

@ -0,0 +1,62 @@
<?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="processing-pipeline-modules">
<title>Processing modules</title>
<shortdesc>The DITA-OT processing pipeline is implemented using Ant. Individual modules within the Ant script are
implemented in either Java or XSLT, depending on such factors as performance or requirements for customization.
Virtually all Ant and XSLT modules can be extended by adding a plug-in to the toolkit; new Ant targets may be
inserted before or after common processing, and new rules may be imported into common XSLT modules to override
default processing.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>specializations
<index-see>DITA
<indexterm>specializations</indexterm></index-see></indexterm>
<indexterm>DITA
<indexterm>specializations</indexterm></indexterm>
<indexterm>processing</indexterm>
<indexterm>Ant
<indexterm>extending</indexterm></indexterm>
<indexterm>Java
<indexterm>extending</indexterm>
<indexterm>processing modules</indexterm></indexterm>
<indexterm>XSLT
<indexterm>processing modules</indexterm></indexterm>
<indexterm>preprocessing
<indexterm>extension points (overview)</indexterm></indexterm>
<indexterm>index
<indexterm>sorting</indexterm></indexterm>
<indexterm>pipelines
<indexterm>Ant module</indexterm></indexterm>
<indexterm>pipelines
<indexterm>Java module</indexterm></indexterm>
<indexterm>locale</indexterm>
</keywords>
</metadata>
</prolog>
<conbody>
<section>
<title>XSLT modules</title>
<p>The XSLT modules use shell files. Typically, each shell file begins by importing common rules that apply to all
topics. This set of common processing rules may in turn import additional common modules, such as those used for
reporting errors or determining the document locale. After the common rules are imported, additional imports can
be included in order to support processing for DITA specializations.</p>
<p>For example, XHTML processing is controlled by the <filepath>xsl/dita2xhtml.xsl</filepath> file. The shell
begins by importing common rules that are applicable to all general topics:
<filepath>xslhtml/dita2htmlImpl.xsl</filepath>. After that, additional XSLT overrides are imported for
specializations that require modified processing. For example, an override for reference topics is imported in
order to add default headers to property tables. Additional modules are imported for tasks, for the highlighting
domain, and for several other standard specializations. After the standard XSLT overrides occur, plug-ins may
add in additional processing rules for local styles or for additional specializations.</p>
</section>
<section>
<title>Java modules</title>
<p>Java modules are typically used when XSLT is a poor fit, such as for processes that make use of standard Java
libraries (like those used for index sorting). Java modules are also used in many cases where a step involves
copying files, such as the initial process where source files are parsed and copied to a temporary processing
directory.</p>
</section>
</conbody>
</concept>

43
dita-ot-3.6/docsrc/reference/processing-structure.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="processing-structure">
<title>Processing structure</title>
<shortdesc>DITA-OT implements a multi-stage, map-driven architecture to process DITA content. Each stage in the
process examines some or all of the content; some stages result in temporary files that are used by later steps,
while others stages result in updated copies of the DITA content. Most of the processing takes place in a temporary
working directory; the source files themselves are never modified.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>architecture</indexterm>
<indexterm>preprocessing</indexterm>
<indexterm>Eclipse Help</indexterm>
<indexterm>HTML Help</indexterm>
<indexterm>XHTML</indexterm>
<indexterm>PDF</indexterm>
<indexterm>HTML5
<indexterm>preprocesing</indexterm></indexterm>
<indexterm>pipelines
<indexterm>description of</indexterm></indexterm>
<indexterm>pipelines
<index-see-also>preprocessing</index-see-also></indexterm>
</keywords>
</metadata>
</prolog>
<conbody>
<p>DITA-OT is designed as a pipeline. Most of the pipeline is common to all output formats; it is known as the
<term>pre-processing stage</term>. In general, any DITA process begins with this common set of pre-processing
routines.</p>
<p>Once the pre-processing is completed, the pipeline diverges based on the requested output format. Some processing
is still common to multiple output formats; for example, Eclipse Help and HTML Help both use the same routines to
generate XHTML topics, after which the two pipelines branch to create different sets of navigation files.</p>
<p>The following image illustrates how the pipeline works for several common output formats: PDF, Eclipse Help, HTML
Help, XHTML, and HTML5.</p>
<note>Other output formats may implement additional processing steps.</note>
<fig>
<title>Diagram of some possible paths through the transformation pipeline</title>
<image href="images/processing-flow.svg" placement="break" width="6.5in"/>
</fig>
</conbody>
</concept>

97
dita-ot-3.6/docsrc/reference/reference.ditamap Normal file
View file

@ -0,0 +1,97 @@
<?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>Reference</title>
<topicref keyref="architecture">
<topicref keyref="processing-structure"/>
<topicref keyref="map-first-preproc"/>
<topicref keyref="processing-pipeline-modules"/>
<topicref keyref="processing-order"/>
<topicref keyref="store-api"/>
<topicref collection-type="sequence" keyref="preprocessing">
<topicref keyref="preprocess-genlist"/>
<topicref keyref="preprocess-debugfilter"/>
<topicref keyref="preprocess-mapref"/>
<topicref keyref="preprocess-branch-filter"/>
<topicref keyref="preprocess-keyref"/>
<topicref keyref="preprocess-copy-to"/>
<topicref keyref="preprocess-conrefpush"/>
<topicref keyref="preprocess-conref"/>
<topicref keyref="preprocess-profile"/>
<topicref keyref="preprocess-topic-fragment"/>
<topicref keyref="preprocess-chunk"/>
<topicref keyref="preprocess-metadata"/>
<topicref keyref="preprocess-maplink"/>
<topicref keyref="preprocess-topicpull"/>
<topicref keyref="preprocess-flagging"/>
<topicref keyref="preprocess-clean-map"/>
<topicref keyref="preprocess-copyfiles"/>
</topicref>
<topicref keyref="html-based-processing">
<topicref keyref="common-html-processing"/>
<topicref keyref="xhtml-processing"/>
<topicref keyref="html5-processing"/>
<topicref keyref="eclipsehelp-processing"/>
<topicref keyref="htmlhelp-processing"/>
</topicref>
<topicref keyref="pdf-transform">
<topicref keyref="pdf-transformation-history"/>
</topicref>
</topicref>
<topicref keyref="dita-spec-support">
<topicref keyref="dita-v1-2-support"/>
<topicref keyref="dita-v1-3-support"/>
<topicref keyref="dita-v2-0-support"/>
<topicref keyref="implementation-dependent-features"/>
<topicref keyref="extended-functionality"/>
<topicref keyref="docs-dita-features"/>
</topicref>
<mapref href="../extension-points/extension-points.ditamap"/>
<mapref href="license.ditamap"/>
<mapref href="glossary.ditamap"/>
<reltable>
<relrow>
<relcell>
<topicref keyref="preprocess-chunk"/>
</relcell>
<relcell>
<topicref keyref="dita12-spec-chunking">
<topicmeta>
<linktext>Chunking definition in the DITA 1.2 specification</linktext>
</topicmeta>
</topicref>
</relcell>
</relrow>
<relrow>
<relcell>
<topicref keyref="preprocess-topic-fragment"/>
</relcell>
<relcell>
<topicref keyref="extended-functionality"/>
</relcell>
</relrow>
<relrow>
<relcell>
<topicref keyref="plugins-installing"/>
<topicref keyref="plugins-removing"/>
</relcell>
<relcell>
<topicref keyref="dita-command-arguments" linking="targetonly"/>
</relcell>
</relrow>
<relrow>
<relcell>
<topicref keyref="extension-points-by-plugin"/>
<topicref keyref="messages"/>
<topicref keyref="dita-ot-params"/>
</relcell>
<relcell>
<topicref keyref="rebuilding-docs" linking="targetonly"/>
</relcell>
</relrow>
</reltable>
</map>

78
dita-ot-3.6/docsrc/reference/store-api.dita Normal file
View file

@ -0,0 +1,78 @@
<?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="store-api">
<title>Store API – Processing in memory</title>
<titlealts>
<navtitle>Store API</navtitle>
</titlealts>
<shortdesc>DITA-OT originally assumed resources would be available on disk and available from file paths. Recent
versions added URI input, so HTTPS resources could be used, but temporary and output resources were still
file-based. DITA-OT 3.6 introduces a new Store API that can process temporary resources in memory instead of writing
them to disk.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>Store API</indexterm>
<indexterm>in-memory processing</indexterm>
</keywords>
</metadata>
</prolog>
<body>
<p>The Store API (<codeph>org.dita.dost.store.Store</codeph>) is a Java abstraction over temporary file operations.
So for example instead of reading resources directly with <codeph>FileInputStream</codeph>, the Store API provides
operations for this. This abstraction allows implementations of the Store API to choose how they handle resources,
enables optimizations or non–file-based storage. Since DITA-OT processes a lot of XML data, the Store API offers
operations for XML processing directly. For example, a read method to directly get a DOM
<codeph>Document</codeph>, instead of opening a file stream manually, parsing it with an XML parser, and getting
the <codeph>Document</codeph> instance from the parser.</p>
<p>The Store API is extendable using Java’s
<xref
href="https://docs.oracle.com/javase/9/docs/api/java/util/ServiceLoader.html"
format="html"
scope="external"
>Resource Loader</xref> with the <codeph>org.dita.dost.store.StoreBuilder</codeph> service. This is a builder
interface to get named <codeph>Store</codeph> instances (“a Store”).</p>
<section id="stream-store">
<title>Stream Store for file-based processing</title>
<p>This Store could also be a File Store, since it uses disk and local files for temporary resources. This is the
traditional DITA-OT implementation, where temporary XML files are stored under the
<codeph>dita.temp.dir</codeph> path.</p>
<p>The Stream Store is activated by setting the <parmname>store-type</parmname> parameter to
<option>file</option>.</p>
<note>To ensure backwards compatibility, the <option>file</option> Store is the default setting in DITA-OT
3.6.</note>
</section>
<section id="cache-store">
<title>Cache Store for in-memory processing</title>
<p>This Store is an in-memory Store, that keeps all temporary resources in memory. The name comes from the feature
of the Store, that it caches the parsed XML after reading. That is, instead of storing XML as a byte array, it
keeps it as a DOM <codeph>Document</codeph> or <apiname>S9api</apiname> <codeph>XdmNode</codeph>. When the same
resource is re-read later, it doesn't have to parse it again, only return the parsed document. Resources that
are not available in the temporary directory are handled with the Stream Store.</p>
<p>While the Store doesn't write anything to the temporary directory, it will still use URIs where the resources
are under the temporary directory. The URIs are simply used for addressing, similarly to URNs. Future releases
of DITA-OT may use some other method of addressing, such as a <codeph>tmp</codeph> URI scheme.</p>
<note type="tip">As of DITA-OT 3.6, the Cache Store can be activated by setting the
<parmname>store-type</parmname> parameter to <option>memory</option>.</note>
</section>
<section id="benefits">
<title>Benefits</title>
<p>The initial implementation of the Cache Store is provided in DITA-OT 3.6 as a preview to allow integration
partners to test this new feature.</p>
<p>
<ph conkeyref="migrating-to-3.6/io-bound"/></p>
<p>The Store API also makes the Saxon <apiname>S9api</apiname> easier to use. It offers an XML document model that
is in most cases easier to work with than DOM. The abstraction Store makes it easier to work with XML, so
various modules don’t need to repeat the same type of XML processing code.</p></section>
<section id="caveats">
<title>Caveats</title>
<p
>Not all custom plug-ins will work with the Cache Store, because they may assume files are used and expect direct file
access for resource operations.</p>
<note type="important">To take advantage of the Store API, custom plug-ins must use DITA-OT XSLT modules in custom
<xmlelement>pipeline</xmlelement> elements instead of Ant’s built-in <xmlelement>xslt</xmlelement> tasks as
recommended in <xref keyref="plugin-coding-conventions"/>.</note>
</section>
</body>
</topic>

170
dita-ot-3.6/docsrc/reference/third-party-software.dita Normal file
View file

@ -0,0 +1,170 @@
<?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="third-party-software">
<title>Third-party software</title>
<shortdesc>DITA Open Toolkit uses third-party software components to provide certain features in the core toolkit,
Java API, and bundled plug-ins.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>PDF
<indexterm>plug-in, required software</indexterm></indexterm>
<indexterm>third-party software</indexterm>
</keywords>
</metadata>
</prolog>
<conbody>
<section>
<title>DITA-OT <keyword keyref="release"/></title>
<p>DITA-OT core processing uses the following third-party software:</p>
<table outputclass="table-hover" frame="none" colsep="0" rowsep="1">
<tgroup cols="3">
<colspec colname="project" colwidth="1*"/>
<colspec colname="version" colwidth="1*"/>
<colspec colname="license" colwidth="2*"/>
<thead>
<row>
<entry>Software</entry>
<entry>Version</entry>
<entry>License</entry>
</row>
</thead>
<tbody>
<row>
<entry>Ant
<indexterm>Ant</indexterm></entry>
<entry><keyword keyref="tool.ant.version"/></entry>
<entry>
<xref keyref="license-apache-2"/>
</entry>
</row>
<row>
<entry>Apache Commons Codec
<indexterm>Apache Commons Codec</indexterm></entry>
<entry><keyword keyref="tool.codec.version"/></entry>
<entry>
<xref keyref="license-apache-2"/></entry>
</row>
<row>
<entry>Apache Commons IO
<indexterm>Apache Commons IO</indexterm></entry>
<entry><keyword keyref="tool.io.version"/></entry>
<entry>
<xref keyref="license-apache-2"/></entry>
</row>
<row>
<entry>Guava
<indexterm>Guava</indexterm></entry>
<entry><keyword keyref="tool.guava.version"/></entry>
<entry>
<xref keyref="license-apache-2"/></entry>
</row>
<row>
<entry>ICU for Java (ICU4J)
<indexterm>ICU for Java (ICU4J)</indexterm></entry>
<entry><keyword keyref="tool.icu4j.version"/></entry>
<entry>
<xref keyref="license-ICU"/></entry>
</row>
<row>
<entry>Logback Classic Module
<indexterm>Logback Classic Module</indexterm></entry>
<entry><keyword keyref="tool.logback.version"/></entry>
<entry>
<xref keyref="license-EPL"/>,
<xref keyref="license-LGPL"/>
</entry>
</row>
<row>
<entry><keyword keyref="tool.saxon.edition"/>
<indexterm>Saxon</indexterm></entry>
<entry><keyword keyref="tool.saxon.version"/></entry>
<entry>
<xref keyref="license-MPL"/></entry>
</row>
<row>
<entry>Simple Logging Facade for Java (SLF4J)
<indexterm>Simple Logging Facade for Java</indexterm></entry>
<entry><keyword keyref="tool.SLF4J.version"/></entry>
<entry>
<xref keyref="license-MIT"/></entry>
</row>
<row>
<entry>Xerces
<indexterm>Xerces</indexterm></entry>
<entry><keyword keyref="tool.xerces.version"/></entry>
<entry>
<xref keyref="license-apache-2"/></entry>
</row>
<row>
<entry>XML APIs
<indexterm>XML APIs</indexterm></entry>
<entry><keyword keyref="tool.xmlapis.version"/></entry>
<entry>
<xref keyref="license-apache-2"/>,
<xref keyref="license-W3C"/></entry>
</row>
<row>
<entry>XML Resolver
<indexterm>XML Resolver</indexterm></entry>
<entry><keyword keyref="tool.resolver.version"/></entry>
<entry>
<xref keyref="license-apache-2"/></entry>
</row>
</tbody>
</tgroup>
</table>
<note>The XML APIs library contains source code for SAX and DOM APIs, which each have their own licenses.</note>
</section>
<section>
<title>PDF plug-in</title>
<p>The <codeph>org.dita.pdf2</codeph> plug-in relies on additional third-party software to generate PDF
output:</p>
<table outputclass="table-hover" frame="none" colsep="0" rowsep="1">
<tgroup cols="3">
<colspec colname="project" colwidth="1*"/>
<colspec colname="version" colwidth="1*"/>
<colspec colname="license" colwidth="1*"/>
<thead>
<row>
<entry>Software</entry>
<entry>Version</entry>
<entry>License</entry>
</row>
</thead>
<tbody>
<row>
<entry>Apache Commons Logging
<indexterm>Apache Commons Logging</indexterm></entry>
<entry>1.0.4</entry>
<entry>
<xref keyref="license-apache-2"/></entry>
</row>
<row>
<entry>Apache XML Graphics
<indexterm>Apache XML Graphics</indexterm></entry>
<entry><keyword keyref="tool.fop.version"/></entry>
<entry>
<xref keyref="license-apache-2"/></entry>
</row>
<row>
<entry>Batik
<indexterm>Batik</indexterm></entry>
<entry>1.13</entry>
<entry>
<xref keyref="license-apache-2"/></entry>
</row>
<row>
<entry>FOP
<indexterm>Apache FOP</indexterm></entry>
<entry><keyword keyref="tool.fop.version"/></entry>
<entry>
<xref keyref="license-apache-2"/></entry>
</row>
</tbody>
</tgroup>
</table>
</section>
</conbody>
</concept>

22
dita-ot-3.6/docsrc/reference/xhtml-processing.dita Normal file
View file

@ -0,0 +1,22 @@
<?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="xhtmldefault">
<title>XHTML processing</title>
<shortdesc>After the XHTML files are generated by the common routine, the <codeph>dita.map.xhtml</codeph> target is
called by the <option>xhtml</option> transformation. This target generates a TOC file called
<filepath>index.html</filepath>, which can be loaded into a frameset.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>HTML
<indexterm>XHTML</indexterm></indexterm>
<indexterm>dita.map.xhtml</indexterm>
<indexterm>targets
<indexterm>XHTML</indexterm></indexterm>
<indexterm>entry file
<indexterm>XHTML</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
</concept>