Merge tag '4.2' into develop

DITA-OT 4.2

* tag '4.2': (38 commits)
  Add CLI not using colours with pipe or redirect #4393
  Hyphenate pre-processing consistently
  Provide additional details on S9API & XSLT3
  Add LwDITA list parsing performance improvements
  Add ancestor directories to .ditaotrc search path
  Add DEBUG to list of message types
  List Java dependency updates
  Add missing CLI options --deliverable & --theme
  Add details on recently resolved issues in 4.2
  Add target release date
  Add details on 4.2 issues tagged “bug”
  Add common CSS changes to migration & re-use in RN
  Add 4.2 migration topic
  Promote map-first HTML5 to release summary
  Add details on remaining enhancements
  Add details on subject scheme enhancements
  Add details on  map-first preprocessing in HTML5
  Add details on additional enhancements
  Add details on LwDITA plug-in v5.7
  Add details on Normalized DITA plug-in v2.0
  ...

extension-points/plugin-extension-points-pre-processing.dita

@@ -32,7 +32,7 @@
       <title>Legacy pre-processing extensions</title>
       <p>The following extension points are available in the original <codeph>preprocess</codeph> pipeline that was used
         by default for all transformations prior to DITA-OT 3.0. These extensions are not available in the newer
-        <xref keyref="map-first-preproc">map-first preprocessing</xref> pipeline (<codeph>preprocess2</codeph>), which
+        <xref keyref="map-first-preproc">map-first pre-processing</xref> pipeline (<codeph>preprocess2</codeph>), which
         is used in the PDF and HTML Help transformations as of DITA-OT 3.0.</p>
       <note conkeyref="conref-task/caution-extend-within-preprocessing"/>
       <dl>

extension-points/plugin-extension-points-xslt-import.dita

@@ -16,7 +16,7 @@
           <indexterm>extension points</indexterm></indexterm>
         <indexterm>extension points
           <indexterm>XSLT</indexterm></indexterm>
-        <indexterm>preprocessing
+        <indexterm>pre-processing
           <indexterm>extension points, XSLT</indexterm></indexterm>
       </keywords>
     </metadata>

extension-points/plugin-extension-points-xslt-parameters.dita

@@ -11,7 +11,7 @@
       <keywords>
         <indexterm>XSLT
           <indexterm>parameters</indexterm></indexterm>
-        <indexterm>preprocessing
+        <indexterm>pre-processing
           <indexterm>extension points, parameters</indexterm></indexterm>
       </keywords>
     </metadata>

extension-points/plugin-extension-points.dita

@@ -16,7 +16,7 @@
           <indexterm>overview</indexterm>
           <indexterm>plug-in</indexterm></indexterm>
         <indexterm>extension points
-          <index-see-also>preprocessing</index-see-also></indexterm>
+          <index-see-also>pre-processing</index-see-also></indexterm>
         <indexterm><filepath>plugin.xml</filepath></indexterm>
         <indexterm>topicmerge
           <index-see>org.dita.pdf2.xsl.topicmerge</index-see></indexterm>

parameters/dita-command-arguments.dita

@@ -155,6 +155,8 @@
             <parmname>--project</parmname>=<varname>file</varname>
           </pt>
           <pd>Publish a project file with multiple deliverables.</pd>
+          <pd>You can add the <parmname>--deliverable</parmname> option to specify a single deliverable in the
+            project.</pd>
           <pd>For more information, see
             <xref keyref="using-project-files"/>.</pd>
         </plentry>
@@ -291,7 +293,7 @@
             <parmname>-d</parmname>
           </pt>
           <pd>Debug logging prints considerably more additional information. The debug log includes all information from
-            the verbose log, plus details on Java classes, additional Ant properties and overrides, preprocessing
+            the verbose log, plus details on Java classes, additional Ant properties and overrides, pre-processing
             filters, parameters, and stages, and the complete build sequence. Debug logging requires additional
             resources and can slow down the build process, so it should only be enabled when further details are
             required to diagnose problems.</pd>
@@ -439,7 +441,15 @@
           <pd>The temporary directory is where DITA-OT writes intermediate files that are generated during the
             transformation process.</pd>
         </plentry>
-        <plentry>
+        <plentry id="theme">
+          <pt>
+            <parmname>--theme</parmname>=<varname>file</varname>
+          </pt>
+          <pd>Publish PDF output with a theme configuration file.</pd>
+          <pd>For more information, see
+            <xref keyref="pdf-themes"/>.</pd>
+        </plentry>
+        <plentry id="verbose">
           <pt>
             <parmname>--verbose</parmname></pt>
           <pt>

parameters/local-properties-file.dita

@@ -13,16 +13,16 @@
       <keywords>
         <indexterm>files
           <indexterm>local.properties</indexterm></indexterm>
-        <indexterm>local.properties file</indexterm>
+        <indexterm><filepath>local.properties</filepath> file</indexterm>
         <indexterm>Windows</indexterm>
         <indexterm>RenderX
-          <indexterm><filepath>local.properties</filepath></indexterm></indexterm>
+          <indexterm><filepath>local.properties</filepath> file</indexterm></indexterm>
         <indexterm>Antenna House
-          <indexterm><filepath>local.properties</filepath></indexterm></indexterm>
+          <indexterm><filepath>local.properties</filepath> file</indexterm></indexterm>
         <indexterm>command line
           <indexterm><filepath>local.properties</filepath> file</indexterm></indexterm>
         <indexterm>Java
-          <indexterm>local.properties file</indexterm></indexterm>
+          <indexterm><filepath>local.properties</filepath> file</indexterm></indexterm>
         <indexterm>PDF
           <indexterm>formatter</indexterm></indexterm>
         <indexterm>formatter

reference/dita-v2-0-support.dita

@@ -170,7 +170,7 @@
     </section>
     <section id="v4.1">
       <title>DITA-OT 4.1</title>
-      <p>DITA-OT 4.1 adds support for additional DITA 2.0 features.</p>
+      <p>DITA-OT 4.1 added support for additional DITA 2.0 features.</p>
       <ul id="added-in-4.1">
         <li>
           <p>DITA 2.0 splits the programming and syntax domains (so you can use one without the other).</p>
@@ -185,6 +185,13 @@
         </li>
       </ul>
     </section>
+    <section id="v4.2">
+      <title>DITA-OT 4.2</title>
+      <p>DITA-OT 4.2 adds support for additional DITA 2.0 features.</p>
+      <ul id="added-in-4.2">
+        <li/>
+      </ul>
+    </section>
     <section>
       <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>

reference/implementation-dependent-features.dita

@@ -85,7 +85,7 @@
       <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>
+      <p>If the scale attribute is not an unsigned integer, no error or warning is thrown during pre-processing.</p>
     </section>
     <section>
       <title>Map processing</title>

reference/map-first-preprocessing.dita

@@ -2,26 +2,27 @@
 <!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>
+  <title>Map-first pre-processing</title>
   <titlealts>
-    <navtitle>Map-first preprocessing</navtitle>
+    <navtitle>Map-first pre-processing</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
+  <shortdesc><ph id="map-first-preproc-desc">DITA-OT provides a map-first pre-processing 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 since been improved and is ready for use in production scenarios. Map-first pre-processing 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 pre-processing</indexterm></indexterm>
+        <indexterm>map-first pre-processing</indexterm>
+        <indexterm>pre-processing
           <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>effect on pre-processing</indexterm></indexterm>
         <indexterm>pipelines
           <indexterm>map first</indexterm></indexterm>
         <indexterm>validate</indexterm>
@@ -33,40 +34,40 @@
     </metadata>
   </prolog>
   <conbody>
-    <p id="map-first-preproc-gain">Whereas the default preprocessing routine handles both maps and topics at the same
+    <p id="map-first-preproc-gain">Whereas the default pre-processing 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
+    <p>The current pre-processing 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
+    <p>The original pre-processing 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 pre-processing 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
+    <p>As of DITA-OT 4.2, the map-first pre-processing pipeline also supports additional subject scheme features.</p>
+    <note id="map-first-preproc-note">The map-first pre-processing 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>
+      names should all be invisible to the build. After further testing and feedback, the new option has been enabled
+      for HTML5 output as of DITA-OT 4.2.</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>
+      <title>How to use map-first pre-processing</title>
+      <p>To use (or test) map-first pre-processing, call the <codeph>preprocess2</codeph> Ant target in your custom
+        transformation types instead of the <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>
+        a normal build to use those properties. As of DITA-OT 4.2, this approach will inherit the map-first
+        pre-processing routine from the HTML5 transformation.</p>
+      <p>In earlier versions, you’d 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 -->
@@ -103,10 +104,10 @@
         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
+        transformation type that is exactly the same, except for pre-processing. 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>
+        but with the new map-first pre-processing:</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"/>
@@ -123,8 +124,6 @@
     </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>

reference/pdf-transform.dita

@@ -18,7 +18,7 @@
           <indexterm><codeph>transform.fo2pdf</codeph></indexterm>
           <indexterm><filepath>topic.fo</filepath></indexterm></indexterm>
         <indexterm>PDF
-          <indexterm>preprocessing</indexterm></indexterm>
+          <indexterm>pre-processing</indexterm></indexterm>
         <indexterm>targets
           <indexterm>PDF</indexterm></indexterm>
         <indexterm>XSLT
@@ -76,7 +76,7 @@
         </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
+          <dd>Sets up pre-processing for flagging based on a DITAVAL file. This step generates the file
               <filepath>stage1a.xml</filepath> in the temporary processing directory.</dd>
         </dlentry>
         <dlentry>

reference/pdf-transformation-history.dita

@@ -32,7 +32,7 @@
   <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>
+      resources were focused primarily on XHTML output and pre-processing.</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

reference/preprocess-branch-filter.dita

@@ -15,7 +15,7 @@
         <indexterm>profiling
           <index-see-also>DITAVAL</index-see-also></indexterm>
         <indexterm>branch filters</indexterm>
-        <indexterm>preprocessing
+        <indexterm>pre-processing
           <indexterm><codeph>branch-filter</codeph></indexterm></indexterm>
         <indexterm><codeph>branch-filter</codeph></indexterm>
       </keywords>

reference/preprocess-chunk.dita

@@ -10,7 +10,7 @@
       <keywords>
         <indexterm><xmlatt>chunk</xmlatt>
           <indexterm>supported methods</indexterm></indexterm>
-        <indexterm>preprocessing
+        <indexterm>pre-processing
           <indexterm><codeph>chunk</codeph></indexterm></indexterm>
         <indexterm><codeph>chunk</codeph></indexterm>
         <indexterm>Java

reference/preprocess-clean-map.dita

@@ -4,11 +4,11 @@
 <concept id="preprocess-clean-map">
   <title>Map cleanup (<codeph>clean-map</codeph>)</title>
   <shortdesc>The <codeph>clean-map</codeph> step removes any elements and attributes that were added to files to support
-    preprocessing.</shortdesc>
+    pre-processing.</shortdesc>
   <prolog>
     <metadata>
       <keywords>
-        <indexterm>preprocessing
+        <indexterm>pre-processing
           <indexterm><codeph>clean-map</codeph></indexterm></indexterm>
         <indexterm><codeph>clean-map</codeph></indexterm>
       </keywords>

reference/preprocess-conref.dita

@@ -16,7 +16,7 @@
         <indexterm><xmlatt>id</xmlatt>
           <indexterm><xmlatt>conref</xmlatt> resolution</indexterm></indexterm>
         <indexterm><xmlatt>xref</xmlatt></indexterm>
-        <indexterm>preprocessing
+        <indexterm>pre-processing
           <indexterm><codeph>conref</codeph></indexterm></indexterm>
         <indexterm><codeph>conref</codeph></indexterm>
         <indexterm>XSLT

reference/preprocess-conrefpush.dita

@@ -9,7 +9,7 @@
   <prolog>
     <metadata>
       <keywords>
-        <indexterm>preprocessing
+        <indexterm>pre-processing
           <indexterm><codeph>conrefpush</codeph></indexterm></indexterm>
         <indexterm><codeph>conrefpush</codeph></indexterm>
         <indexterm>Java

reference/preprocess-copy-to.dita

@@ -9,7 +9,7 @@
     <metadata>
       <keywords>
         <indexterm><xmlatt>copy-to</xmlatt></indexterm>
-        <indexterm>preprocessing
+        <indexterm>pre-processing
           <indexterm><codeph>copy-to</codeph></indexterm></indexterm>
         <indexterm><codeph>copy-to</codeph></indexterm>
       </keywords>

reference/preprocess-copyfiles.dita

@@ -11,7 +11,7 @@
       <keywords>
         <indexterm>DITAVAL
           <indexterm><codeph>copy-files</codeph> preprocess step</indexterm></indexterm>
-        <indexterm>preprocessing
+        <indexterm>pre-processing
           <indexterm><codeph>copy-files</codeph></indexterm></indexterm>
         <indexterm><codeph>copy-files</codeph></indexterm>
         <indexterm>images

reference/preprocess-debugfilter.dita

@@ -14,7 +14,7 @@
         <indexterm><xmlatt>xtrc</xmlatt></indexterm>
         <indexterm>DITAVAL
           <indexterm><codeph>debug-filter</codeph> preprocess step</indexterm></indexterm>
-        <indexterm>preprocessing
+        <indexterm>pre-processing
           <indexterm><codeph>debug-filter</codeph></indexterm></indexterm>
         <indexterm><codeph>debug-filter</codeph></indexterm>
         <indexterm>debugging