Merge branch 'hotfix/4.2.1'

* hotfix/4.2.1: Favor JDKs & add package managers as Java sources Update <shortdesc> w/ maintenance release pattern Add details on issues resolved in 4.2.1 Remove redundant Contributors section Add standard intro to maintenance release section Mark latest hotfix updates Bump Docker image version to ”4.2.1“ Bump 'maintenance-version' key to “4.2.1” Draft 4.2.1 Release Notes (#541) Cache Node.js and Java dependencies in GitHub Actions Update Node.js version in GitHub Actions to 20.x Add NVM configuration for setting local Node.js version Update GitHub Actions' action versions Fall back to archive.org for HTML Help Workshop † Fix typos in documentation and code (#538) Revise font-selection-strategy caveat for FOP 2.9 Update docs GitHub Actions for 4.2 (#535)
dita-ot · Feb 29, 2024 · 6c5961d · 6c5961d
2 parents bf7ea79 + bb6d74f
commit 6c5961d
Show file tree

Hide file tree

Showing 20 changed files with 107 additions and 39 deletions.
diff --git a/.github/actions/render/action.yml b/.github/actions/render/action.yml
@@ -6,19 +6,21 @@ inputs:
     default: 'master'
   DITA_OT_VERSION:
     description: 'DITA-OT version used for rendering'
-    default: '4.1.2'
+    default: '4.2'
 runs:
   using: 'composite'
   steps:
     - name: Set up JDK 17
-      uses: actions/setup-java@v3
+      uses: actions/setup-java@v4
       with:
         distribution: temurin
         java-version: 17
+        cache: 'gradle'
     - name: Set Node.js version 12.x
-      uses: actions/setup-node@v1
+      uses: actions/setup-node@v4
       with:
-        node-version: 12.x
+        node-version: '20.x'
+        cache: 'npm'
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
       with:

diff --git a/.github/workflows/prettier.yml b/.github/workflows/prettier.yml
@@ -25,7 +25,7 @@ jobs:
       - name: Set up Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '18.x'
+          node-version: '20.x'
           cache: 'npm'
 
       - name: Install dependencies

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -17,7 +17,7 @@ jobs:
     runs-on: ubuntu-latest
     env:
       WEBSITE_PLUGIN_BRANCH: 'master'
-      DITA_OT_VERSION: '4.1.2'
+      DITA_OT_VERSION: '4.2'
     steps:
       - name: Parse arguments
         run: |
@@ -44,6 +44,7 @@ jobs:
         with:
           distribution: temurin
           java-version: 17
+          cache: 'gradle'
       - name: Check out website
         uses: actions/checkout@v4
         with:
@@ -105,7 +106,6 @@ jobs:
           path: website
           labels: |
             release-updates
-
   update-ci:
     runs-on: ubuntu-latest
     steps:
@@ -116,12 +116,10 @@ jobs:
           else
             echo "VERSION=${{ github.event.inputs.dita-ot-version }}" >> $GITHUB_ENV
           fi
-
       - name: Check out docs
         uses: actions/checkout@v4
         with:
           ref: develop
-
       - name: Update GitHub Actions release workflow
         uses: mikefarah/yq@master
         with:
@@ -130,7 +128,6 @@ jobs:
         uses: mikefarah/yq@master
         with:
           cmd: yq -i '.inputs.DITA_OT_VERSION.default = "${{ env.VERSION }}"' '.github/actions/render/action.yml'
-
       - name: Create release PR
         uses: peter-evans/create-pull-request@v6
         with:

diff --git a/.nvmrc b/.nvmrc
@@ -0,0 +1 @@
+20.11.1
diff --git a/parameters/ant-parameters-details.dita b/parameters/ant-parameters-details.dita
@@ -673,7 +673,7 @@
             <pd conaction="pushreplace" conref="parameters-pdf.dita#pdf/org.dita.pdf2.i18n.enabled.desc">
               <p>Enables internationalization (I18N) font processing to provide per-character font selection for FO
                 renderers that do not support the <codeph>font-selection-strategy</codeph> property (such as Apache
-                FOP).
+                FOP prior to version 2.9).
                 <indexterm>Apache FOP
                   <indexterm>I18N</indexterm></indexterm>
                 <indexterm>FOP
@@ -692,9 +692,10 @@
                 <li><option>true</option> (default) — Enables font mapping</li>
                 <li><option>false</option> — Disables font mapping</li>
               </ul>
-              <note type="tip">If you don’t use custom character mappings, turning off font mapping makes it easier to
-                define custom fonts simply by changing font names in the XSL attributes files of your custom PDF
-                plug-in. For details, see
+              <note type="tip">DITA-OT 4.2 includes FOP 2.9, which supports <codeph>font-selection-strategy</codeph>. As
+                of this version (or if you don’t use custom character mappings), you can turn off font mapping and
+                specify fonts directly in the XSL attributes files of your custom PDF plug-in. For background
+                information, see
                 <xref keyref="jelovirt-on-pdf2-i18n"/>.</note>
             </pd>
           </plentry>

diff --git a/reference/extended-functionality.dita b/reference/extended-functionality.dita
@@ -11,7 +11,7 @@
 
   <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>
+    indentation, add line numbers or display whitespace characters in code blocks.</shortdesc>
   <prolog>
     <metadata>
       <keywords>

diff --git a/reference/markdown/Common-syntax.md b/reference/markdown/Common-syntax.md
@@ -163,7 +163,7 @@ Term
 <dl>
   <dlentry>
     <dt>Term</dt>
-    <dd>Defintion.</dd>
+    <dd>Definition.</dd>
   </dlentry>
 </dl>
 ```

diff --git a/reference/processing-structure.dita b/reference/processing-structure.dita
@@ -17,7 +17,7 @@
         <indexterm>XHTML</indexterm>
         <indexterm>PDF</indexterm>
         <indexterm>HTML5
-          <indexterm>preprocesing</indexterm></indexterm>
+          <indexterm>preprocessing</indexterm></indexterm>
         <indexterm>pipelines
           <indexterm>description of</indexterm></indexterm>
         <indexterm>pipelines

diff --git a/release-notes/index.dita b/release-notes/index.dita
@@ -8,7 +8,8 @@
   </titlealts>
 
   <abstract>
-    <shortdesc><ph conref="#v4.2/summary"/></shortdesc>
+    <shortdesc>DITA Open Toolkit <keyword keyref="maintenance-version"/> is a maintenance release that fixes issues
+      reported in DITA-OT <keyword keyref="release"/>, which <ph conref="#v4.2/summary"/>.</shortdesc>
     <p conkeyref="conref-task/semver-info"/>
     <note type="tip"><ph conkeyref="conref-task/download-ot"/></note>
   </abstract>
@@ -25,6 +26,49 @@
     </refbody>
   </reference>
 
+  <reference id="v4.2.1" outputclass="mark">
+    <title>DITA-OT <keyword keyref="maintenance-version"/>
+      <ph outputclass="small text-muted">(work in progress)</ph>
+    </title>
+    <refbody>
+      <section id="bugs">
+        <p>DITA Open Toolkit <keyword keyref="maintenance-version"/> is a maintenance release that includes the
+          following bug fixes.</p>
+        <!-- https://github.com/dita-ot/dita-ot/issues?q=milestone%3A4.2.1+is%3Aclosed+label%3Abug+sort%3Acreated-asc -->
+        <ul>
+          <li id="4401">When using the in-memory store, earlier versions of the map-first pre-processing pipeline failed
+            to initialize the temporary directory. The directory is now created to ensure that files are processed
+            correctly.
+            <xref href="https://github.com/dita-ot/dita-ot/pull/4401" format="html" scope="external">#4401</xref>
+          </li>
+          <li id="4402">A NullPointerException that occured when using the in-memory store with map-first
+            pre-processing has also been fixed.
+            <xref href="https://github.com/dita-ot/dita-ot/pull/4402" format="html" scope="external">#4402</xref>
+          </li>
+          <li id="4405">In DITA-OT 4.2, the HTML5 transformation was updated to include map-level
+              <xmlelement>keywords</xmlelement> metadata in the table-of-contents file <filepath>index.html</filepath>.
+            However, this inadvertently also included variable definition keywords from nested topic references.
+            Processing has been updated to only include top-level map keyword metadata.
+            <xref href="https://github.com/dita-ot/dita-ot/issues/4405" format="html" scope="external">#4405</xref>,
+            <xref href="https://github.com/dita-ot/dita-ot/pull/4418" format="html" scope="external">#4418</xref>
+          </li>
+          <li id="4406">The command-line interface in DITA-OT 4.2 prints colored messages in several additional cases,
+            but these changes accidentally removed the logging level prefixes in terminal environments that don’t
+            support color. These message prefixes now appear in all environments, regardless of color support.
+            <xref href="https://github.com/dita-ot/dita-ot/issues/4406" format="html" scope="external">#4406</xref>
+            <xref href="https://github.com/dita-ot/dita-ot/pull/4409" format="html" scope="external">#4409</xref>
+          </li>
+          <li id="4416">DITA-OT 4.2 pruned logging level prefixes from messages by removing anything that appeared
+            between square brackets <codeph>][</codeph> and <codeph>]</codeph>, but this also dropped custom prefixes.
+            Logging has been updated to only remove prefixes that match the default level names like
+              <codeph>INFO</codeph> or <codeph>WARN</codeph>.
+            <xref href="https://github.com/dita-ot/dita-ot/pull/4416" format="html" scope="external">#4416</xref>
+          </li>
+        </ul>
+      </section>
+    </refbody>
+  </reference>
+
   <reference id="v4.2">
     <title>DITA-OT <keyword keyref="release"/>
       <ph outputclass="small text-muted"> released February 11, 2024</ph>
@@ -40,12 +84,10 @@
     </prolog>
     <refbody>
       <section>
-        <p><ph id="summary">DITA Open Toolkit Release <keyword
-              keyref="release"
-            /> uses map-first pre-processing for HTML5
-            output and includes a new local configuration file, better CLI messages with support for overrides, a new
-            version of the Lightweight DITA plug-in with enhancements to Markdown processing, and updates for the latest
-            DITA 2.0 draft standard.</ph></p>
+        <p>DITA Open Toolkit Release <keyword keyref="release"/>
+          <ph id="summary">uses map-first pre-processing for HTML5 output and includes a new local configuration file,
+            better CLI messages with support for overrides, a new version of the Lightweight DITA plug-in with
+            enhancements to Markdown processing, and updates for the latest DITA 2.0 draft standard</ph>.</p>
       </section>
 
       <!-- https://github.com/dita-ot/dita-ot/issues?q=milestone%3ANext+is%3Aclosed+label%3Afeature+sort%3Acreated-asc -->

diff --git a/resources/dita-ot-doc.css b/resources/dita-ot-doc.css
@@ -844,7 +844,7 @@ h2 .codeph {
 }
 
 /****************************************
-Basic identation, padding, and margins
+Basic indentation, padding, and margins
 ****************************************/
 
 @media screen and (min-width: 992px) {

diff --git a/resources/external-links.ditamap b/resources/external-links.ditamap
@@ -343,12 +343,12 @@
     </keydef>
     <keydef
       keys="download.html-help-workshop"
-      href="http://msdn.microsoft.com/en-us/library/windows/desktop/ms669985%28v=vs.85%29.aspx"
+      href="http://web.archive.org/web/20160201063255/http://download.microsoft.com/download/0/A/9/0A939EF6-E31C-430F-A3DF-DFAE7960D564/htmlhelp.exe"
       scope="external"
       format="html"
     >
       <topicmeta>
-        <linktext>msdn.microsoft.com</linktext>
+        <linktext>web.archive.org</linktext>
       </topicmeta>
     </keydef>
     <keydef
@@ -859,6 +859,16 @@
         <linktext>CommonMark</linktext>
       </topicmeta>
     </keydef>
+    <keydef
+      keys="chocolatey"
+      href="https://chocolatey.org/"
+      scope="external"
+      format="html"
+    >
+      <topicmeta>
+        <linktext>Chocolatey</linktext>
+      </topicmeta>
+    </keydef>
     <keydef
       keys="dita-adoption-tc"
       href="https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=dita-adoption"
@@ -1029,6 +1039,16 @@
         <linktext>Sass</linktext>
       </topicmeta>
     </keydef>
+    <keydef
+      keys="sdkman"
+      href="https://sdkman.io/jdks"
+      scope="external"
+      format="html"
+    >
+      <topicmeta>
+        <linktext>SDKMAN!</linktext>
+      </topicmeta>
+    </keydef>
     <keydef
       keys="python-markdown-attlists"
       href="https://python-markdown.github.io/extensions/attr_list/"

diff --git a/resources/key-definitions.ditamap b/resources/key-definitions.ditamap
@@ -26,7 +26,7 @@
   <keydef keys="maintenance-version">
     <topicmeta>
       <keywords>
-        <keyword>4.2</keyword>
+        <keyword>4.2.1</keyword>
       </keywords>
     </topicmeta>
   </keydef>

diff --git a/resources/reusable-components.dita b/resources/reusable-components.dita
@@ -131,14 +131,18 @@
         <indexterm>OpenJDK</indexterm>
         <indexterm>Oracle JDK</indexterm>
         <ul>
-          <li>You can download the Oracle JRE or JDK from
+          <li>You can download Oracle distributions from
             <xref keyref="download.oracle-jdk"/> under commercial license.</li>
           <li>Eclipse Temurin is the free OpenJDK distribution available from
             <xref keyref="download.openjdk"/>.</li>
           <li>Free OpenJDK distributions are also provided by
             <xref keyref="download.openjdk.corretto"/>,
             <xref keyref="download.openjdk.azul"/>, and
             <xref keyref="download.openjdk.redhat"/>.</li>
+          <li>Java versions are also available via package managers such as
+            <xref keyref="chocolatey"/>,
+            <xref keyref="homebrew"/>, or
+            <xref keyref="sdkman"/></li>
         </ul>
       </p>
       <p id="java-bc">

diff --git a/samples/concepts/tools.xml b/samples/concepts/tools.xml
@@ -15,7 +15,7 @@
       <li>Level</li>
       <li>Saws</li>
       <li>Drill</li>
-      <li>Air pressure guage</li>
+      <li>Air pressure gauge</li>
       <li>Spade</li>
       <li>Rake</li>
     </ul>

diff --git a/samples/docker/Dockerfile b/samples/docker/Dockerfile
@@ -1,5 +1,5 @@
 # Use the latest DITA-OT image ↓ as parent:
-FROM ghcr.io/dita-ot/dita-ot:4.2
+FROM ghcr.io/dita-ot/dita-ot:4.2.1
 
 # Install a custom plug-in from a remote location:
 RUN dita --install https://github.com/infotexture/dita-bootstrap/archive/master.zip

diff --git a/samples/taskbook/webtrouble.dita b/samples/taskbook/webtrouble.dita
@@ -3,7 +3,7 @@
 <!--  This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license.  -->
 <!-- (c) Copyright IBM Corp. 2004, 2005 All Rights Reserved. -->
 <task id="webtrouble" xml:lang="en-us">
-  <title>Troublshooting Web Server problems</title>
+  <title>Troubleshooting Web Server problems</title>
   <shortdesc>There are several things to try if your Web Server is not functioning properly.</shortdesc>
   <prolog>
     <metadata>

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

diff --git a/topics/implement-saxon-extension-functions.dita b/topics/implement-saxon-extension-functions.dita
@@ -39,7 +39,7 @@
             <filepath>META-INF/services</filepath> in the compiled JAR that your plug-in provides. Each line of the file
           must be the name of a class that implements <codeph
           >net.sf.saxon.lib.ExtensionFunctionDefinition</codeph>: <codeblock>com.example.saxon.functions.Add
-com.example.saxon.functions.Substract</codeblock>
+com.example.saxon.functions.Subtract</codeblock>
           <p>You can create the file using <xmlelement>service</xmlelement> elements in an Ant
               <xmlelement>jar</xmlelement>
             task:<codeblock outputclass="language-xml">&lt;jar destfile="${basedir}/target/lib/example-saxon.jar">

diff --git a/topics/plugin-configfile.dita b/topics/plugin-configfile.dita
@@ -10,7 +10,7 @@
     <metadata>
       <keywords>
         <indexterm>plug-ins
-          <indexterm>identfiers</indexterm></indexterm>
+          <indexterm>identifiers</indexterm></indexterm>
         <indexterm>plug-ins
           <indexterm><filepath>plugin.xml</filepath></indexterm></indexterm>
         <indexterm>metadata
@@ -82,7 +82,7 @@
             </simpletable>
             <p id="extension-point-ids">Like plug-in identifiers, extension point identifiers are composed of one or
               more dot-delimited tokens.</p>
-            <note id="entension-point-ids-note">Extension point identifiers should begin with the identifier of the
+            <note id="extension-point-ids-note">Extension point identifiers should begin with the identifier of the
               defining plug-in and append one or more tokens, for example, <codeph>org.dita.example.pre</codeph>.</note>
             <fig>
               <title>Sample <xmlelement>extension-point</xmlelement> element</title>

diff --git a/topics/prerequisite-software.dita b/topics/prerequisite-software.dita
@@ -37,7 +37,7 @@
       <p>DITA-OT requires the following software applications:
         <dl>
           <dlentry>
-            <dt>Java Runtime Environment (JRE) or Java Development Kit (JDK)</dt>
+            <dt>Java Development Kit (JDK) or Java Runtime Environment (JRE)</dt>
             <dd>
               <p conkeyref="reusable-components/java-clients"/>
               <note>This is the <i>only</i> prerequisite that you need to install. All other required software is
@@ -59,8 +59,9 @@
       <p>Depending on the type of output that you want to generate, you might need the following applications:
         <dl>
           <dlentry>
-            <dt>Microsoft Help Workshop</dt>
-            <dd>Required for generating HTML help. You can download the Help Workshop from
+            <dt>HTML Help Workshop</dt>
+            <dd>Microsoft no longer provides the software required for generating Compiled HTML Help (.chm) files. You
+              can download an archived copy of the HTML Help Workshop from the Internet Archive’s Wayback Machine at
               <xref keyref="download.html-help-workshop"/>.</dd>
           </dlentry>
           <dlentry>