🚧 Draft 4.4 docs

build.gradle

@@ -3,14 +3,12 @@ buildscript {
         mavenCentral()
     }
     dependencies {
-        classpath 'net.sf.saxon:Saxon-HE:10.6'
+        classpath 'net.sf.saxon:Saxon-HE:12.9'
     }
 }
 
 plugins {
-    id 'io.github.jyjeanne.dita-ot-gradle' version '2.3.2'
-    // Removed: 'com.github.eerohele.saxon-gradle' - not Configuration Cache compatible
-    // Replaced with: inline XsltTransformTask class below
+    id 'io.github.jyjeanne.dita-ot-gradle' version '2.8.2'
 }
 
 import org.gradle.api.DefaultTask
@@ -24,7 +22,7 @@ import javax.xml.transform.stream.StreamSource
 
 /**
  * Gradle 9 compatible XSLT transformation task using Saxon-HE.
- * Replaces eerohele/saxon-gradle which is not Configuration Cache compatible.
+ * Replaces eerohele/saxon-gradle, which is not configuration cache compatible.
  */
 @CacheableTask
 abstract class XsltTransformTask extends DefaultTask {
@@ -77,7 +75,7 @@ abstract class XsltTransformTask extends DefaultTask {
     }
 
     // DSL methods for backward compatibility with saxon-gradle syntax
-    // Using layout API for Configuration Cache compatibility
+    // Using layout API for configuration cache compatibility
     void input(Object path) {
         inputFile.set(project.layout.projectDirectory.file(path.toString()))
     }
@@ -109,7 +107,7 @@ String ditaHomeSrc = getPropertyOrDefault('ditaHomeSrc', ditaHome)
 String configDir = "${ditaHomeSrc}/config"
 String ditavalFile = "${projectDirPath}/platform.ditaval"
 
-// Defer file existence check for Configuration Cache compatibility
+// Defer file existence check for configuration cache compatibility
 Boolean toolkitBuild = providers.provider {
     file("${projectDirPath}/../lib/dost.jar").exists()
 }.get()
@@ -159,7 +157,7 @@ task generatePlatformFilter {
         // Use System properties for OS detection (public API)
         def osName = System.getProperty('os.name').toLowerCase()
         def platformName = osName.contains('win') ? 'windows' :
-                          osName.contains('mac') ? 'mac' : 'unix'
+                           osName.contains('mac') ? 'mac' : 'unix'
 
         // Generate the ditaval file using modern Gradle file operations
         outputFile.asFile.text = """<?xml version="1.0" encoding="UTF-8"?>
@@ -187,14 +185,12 @@ task autoGenerate(dependsOn: [messages, params, extensionPoints, generatePlatfor
 task pdf(type: DitaOtTask, dependsOn: autoGenerate) {
     group = 'documentation'
     description = 'Build PDF documentation.'
-    // Set DITA-OT directory: pass as parameter -PditaHome or fall back to parent when run in core repo.
     ditaOt file(findProperty('ditaHome') ?: ditaHome)
     input "${projectDirPath}/userguide-book.ditamap"
     output outputDir
     transtype 'pdf'
     filter "${projectDirPath}/resources/pdf.ditaval"
 
-    // Use ditaProperties MapProperty directly for v2.3.0 compatibility
     ditaProperties.put('args.chapter.layout', 'BASIC')
     ditaProperties.put('args.gen.task.lbl', 'YES')
     ditaProperties.put('include.rellinks', '#default external')
@@ -205,14 +201,12 @@ task pdf(type: DitaOtTask, dependsOn: autoGenerate) {
 task html(type: DitaOtTask, dependsOn: autoGenerate) {
     group = 'documentation'
     description = 'Build HTML5 documentation.'
-    // Set DITA-OT directory: pass as parameter -PditaHome or fall back to parent when run in core repo.
     ditaOt file(findProperty('ditaHome') ?: ditaHome)
     input "${projectDirPath}/userguide.ditamap"
     output outputDir
     transtype 'html5'
     filter "${projectDirPath}/resources/html.ditaval"
 
-    // Use ditaProperties MapProperty directly for v2.3.0 compatibility
     ditaProperties.put('args.copycss', 'yes')
     ditaProperties.put('args.css', 'dita-ot-doc.css')
     ditaProperties.put('args.csspath', 'css')
@@ -227,14 +221,12 @@ task html(type: DitaOtTask, dependsOn: autoGenerate) {
 task htmlhelp(type: DitaOtTask, dependsOn: autoGenerate) {
     group = 'documentation'
     description = 'Build HTML Help (.chm) documentation.'
-    // Set DITA-OT directory: pass as parameter -PditaHome or fall back to parent when run in core repo.
     ditaOt file(findProperty('ditaHome') ?: ditaHome)
     input "${projectDirPath}/userguide.ditamap"
     output outputDir
     transtype 'htmlhelp'
     filter ditavalFile
 
-    // Use ditaProperties MapProperty directly for v2.3.0 compatibility
     ditaProperties.put('args.copycss', 'yes')
     ditaProperties.put('args.css', 'dita-ot-doc.css')
     ditaProperties.put('args.csspath', 'css')
@@ -256,16 +248,13 @@ task htmlhelp(type: DitaOtTask, dependsOn: autoGenerate) {
     }
 }
 
-task cleanOutput {
+task cleanOutput(type: Delete) {
     group = 'build'
     description = 'Delete the output directory.'
-    doLast {
-        delete outputDir
-    }
+    delete file(outputDir)
 }
 
-// Get git commit hash using Gradle 9 compatible Provider API
-// Uses providers.exec() instead of deprecated project.exec()
+// Get Git commit hash using Gradle 9 compatible Provider API
 def gitCommitHash = providers.exec {
     commandLine 'git', 'rev-parse', 'HEAD'
     ignoreExitValue = true
@@ -274,36 +263,29 @@ def gitCommitHash = providers.exec {
 task gitMetadata {
     group = 'build'
     description = 'Log git commit metadata.'
-    // This task just logs the git commit for reference
     doLast {
         logger.lifecycle("Git commit: ${gitCommitHash}")
     }
-
-    // Mark outputs to help with up-to-date checking
-    outputs.upToDateWhen { false } // Always run since git commit changes frequently
+    outputs.upToDateWhen { false }
 }
 
 task site(type: DitaOtTask) {
     group = 'documentation'
     description = 'Build website documentation.'
     dependsOn 'messages', 'params', 'extensionPoints', 'gitMetadata'
 
-    // Set DITA-OT directory: pass as parameter -PditaHome or fall back to parent when run in core repo.
     ditaOt file(findProperty('ditaHome') ?: ditaHome)
     input file("${projectDirPath}/site.ditamap")
     output getPropertyOrDefault('outputDir', layout.buildDirectory.dir("site").get().asFile.path)
     filter "${projectDirPath}/resources/site.ditaval"
-
     transtype 'org.dita-ot.html'
 
     // Evaluate the noCommitMeta flag at configuration time
     def includeCommitMeta = !providers.gradleProperty('noCommitMeta').map { Boolean.parseBoolean(it) }.getOrElse(false)
 
-    // Use ditaProperties MapProperty directly for v2.3.0 compatibility
     ditaProperties.put('args.gen.task.lbl', 'YES')
     ditaProperties.put('args.rellinks', 'noparent')
     if (includeCommitMeta) {
-        // Use the git commit hash obtained at configuration time
         ditaProperties.put('commit', gitCommitHash)
     }
 }

gradle.properties

@@ -1,10 +1,7 @@
 # Fix Java memory errors with Gradle 5.2
 org.gradle.jvmargs = -Xmx1024m
 
-# Gradle 8 features for better performance and caching
-# ↓ Not supported by eerohele/dita-ot-gradle ↓
-# org.gradle.configuration-cache=true
-# org.gradle.configuration-cache.problems=warn
-# ↑ Not supported by eerohele/dita-ot-gradle ↑
+# Gradle 9 features for better performance and caching
+org.gradle.configuration-cache=true
 org.gradle.parallel=true
 org.gradle.caching=true

parameters/ant-parameters-details.dita

@@ -223,8 +223,7 @@
             </pt>
             <pd conaction="mark" conref="parameters-base.dita#base/dita.input.valfile.desc"/>
             <pd conaction="pushafter">
-              <note type="notice">This parameter is deprecated in favor of the <parmname>args.filter</parmname>
-                parameter.</note>
+              <note type="notice">This parameter is deprecated; use <parmname>args.filter</parmname> instead.</note>
             </pd>
           </plentry>
           <plentry id="filter-stage">
@@ -522,8 +521,7 @@
             <pd conaction="pushafter">
               <div id="args.hide.parent.link.details">
                 <ph audience="xslt-customizer">Corresponds to the XSLT parameter <parmname>NOPARENTLINK</parmname>.</ph>
-                <note type="notice">This parameter is deprecated in favor of the <parmname>args.rellinks</parmname>
-                  parameter.</note>
+                <note type="notice">This parameter is deprecated; use <parmname>args.rellinks</parmname> instead.</note>
               </div></pd>
           </plentry>
           <plentry id="args.outext">
@@ -713,15 +711,21 @@
                 <xref keyref="jelovirt-on-pdf2-i18n"/>.</note>
             </pd>
           </plentry>
-          <plentry id="outputFile.base">
+          <plentry id="outputFile.base" importance="deprecated">
             <pt>
               <parmname>outputFile.base</parmname>
+              <ph>
+                <indexterm>deprecated features
+                  <indexterm><parmname>outputFile.base</parmname></indexterm></indexterm></ph>
             </pt>
             <pd conaction="mark" conref="parameters-pdf.dita#pdf/outputFile.base.desc"/>
             <pd conaction="pushafter">By default, the PDF file uses the base filename of the input
                 <filepath>.ditamap</filepath> file.
               <indexterm>DITA maps
-                <indexterm>PDF file name</indexterm></indexterm></pd>
+                <indexterm>PDF file name</indexterm></indexterm>
+              <note type="notice">This parameter is deprecated since DITA-OT 3.0; use
+                <parmname>args.output.base</parmname> instead.</note>
+            </pd>
           </plentry>
           <plentry id="pdf.formatter">
             <pt>
@@ -738,18 +742,29 @@
                 <indexterm>formatter</indexterm></indexterm>
             </pd>
           </plentry>
-          <plentry id="publish.required.cleanup" importance="deprecated">
+          <plentry
+            id="publish.required.cleanup"
+            importance="deprecated"
+            conaction="pushreplace"
+            conref="parameters-pdf.dita#pdf/publish.required.cleanup"
+          >
+            <!-- Replace entire plentry element to pick up deprecated status (not currently marked as such in code) -->
             <pt>
               <parmname>publish.required.cleanup</parmname>
               <ph>
                 <indexterm>deprecated features
+                  <indexterm><parmname>publish.required.cleanup</parmname></indexterm></indexterm>
+                <indexterm>parameters
                   <indexterm><parmname>publish.required.cleanup</parmname></indexterm></indexterm></ph>
             </pt>
-            <pd conaction="mark" conref="parameters-pdf.dita#pdf/publish.required.cleanup.desc"/>
-            <pd conaction="pushafter">The default value is the value of the <parmname>args.draft</parmname> parameter.
-                <ph audience="xslt-customizer">Corresponds to the XSLT parameter
-                  <parmname>publishRequiredCleanup</parmname>.</ph><note type="notice">This parameter is deprecated in
-                favor of the <parmname>args.draft</parmname> parameter.</note></pd>
+            <pd id="publish.required.cleanup.desc">Specifies whether draft-comment and required-cleanup elements are
+              included in the output. The allowed values are <option>yes</option>, and <option>no</option>.</pd>
+            <!-- Add context previously pushed after .desc -->
+            <pd>The default value is the value of the <parmname>args.draft</parmname> parameter.
+              <ph audience="xslt-customizer">Corresponds to the XSLT parameter
+                  <parmname>publishRequiredCleanup</parmname>.</ph>
+              <note type="notice">This parameter is deprecated; use
+                  <parmname>args.draft</parmname> instead.</note></pd>
           </plentry>
         </parml>
       </section>

parameters/dita-command-arguments.dita

@@ -376,6 +376,18 @@
               <xref href="#./verbose"><parmname>--verbose</parmname></xref> option (or <parmname>-v</parmname>).</note>
           </pd>
         </plentry>
+        <plentry id="logger">
+          <pt>
+            <parmname>--logger</parmname>=<varname>json</varname>
+          </pt>
+          <pd>
+            <p>Generate a structured log in JSON format. Each log message generates a JSON object on its own line. JSON
+              logging disables colored output.</p>
+            <p>If log is written to a file with <parmname
+              >--logfile</parmname>, the log will be generated as a JSON array
+            where each log message is a JSON object as an array item.</p>
+          </pd>
+        </plentry>
         <plentry>
           <pt>
             <parmname>--no-color</parmname>