Migrate to dita-ot-gradle plugin v2.8.2

[jyjeanne]

@infotexture ## Key Changes

• Update dita-ot-gradle plugin from v2.3.2 to v2.8.1 to benefits new improvments
• Enable Configuration Cache for faster incremental builds
• Add new verification tasks: validateDita and checkLinks

---

Motivation and Context

Gradle 9.0 removes several deprecated APIs and makes Configuration Cache the recommended execution mode.

This PR ensures the documentation build works with Gradle 8.x, 9.x, and future versions, while enabling up to 77% faster incremental builds via Configuration Cache.

---

How Has This Been Tested?

Test	Gradle 8.14.3	Gradle 9.0	Gradle 9.3
./gradlew help --warning-mode all	✓ PASS	✓ PASS	✓ PASS
./gradlew --configuration-cache	✓ PASS	✓ PASS	✓ PASS
./gradlew dist -PditaHome=...	✓ PASS	✓ PASS	✓ PASS
./gradlew cleanOutput dist	✓ PASS	✓ PASS	✓ PASS

Full Build Tested with DITA-OT 4.3.5

• PDF generation: ✓ (5.06 MB, 1669 files)
• HTML5 generation: ✓ (2178 files)
• Configuration Cache: ✓ stored and reused

---

Type of Changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)

---

Documentation and Compatibility

Documentation Changes

• None required — build infrastructure change only

Backwards Compatibility

• No breaking changes for end users
• Maintains backward compatibility with Gradle 8.x
• Enables forward compatibility with Gradle 9.x+
• Same task names and behavior preserved

---

New Features

Task	Description	Command
validateDita	Validate DITA content without transformation	./gradlew validateDita
checkLinks	Check for broken internal links	./gradlew checkLinks
verify	Run all verification tasks	./gradlew verify

---

Checklist

• My code follows the code style of this project
• Build tested with Gradle 8.14.3, 9.0, and 9.3
• Configuration Cache enabled and verified
• No deprecation warnings with --warning-mode all
• Full documentation build (PDF + HTML) verified

[infotexture]

@jyjeanne 🙏 Thanks for submitting this. Interesting ideas here.

Makes sense to strip the comments from our earlier work on the build file.
Certainly much cleaner without them. 👍

I ran the docs build with these changes, and output was generated as expected, so it still works with these changes.

The additional progress indicators look useful:

Starting DITA-OT transformation
  [==>                           ] 10% - Preprocessing
  [====================>         ] 70% - Transforming (45 files)
  [=======================>      ] 80% - Generating content (77 files)

The PDF transformation is much noisier now, as it logs all sorts of FOP warnings:

[WARN] The contents of fo:region-body on page 1 exceed its viewport by 48187 millipoints. (See position 1:1663)
[WARN] Property ID "unique_348" (found on "fo:wrapper") previously used; ID values must be unique within a document! Any reference to it will be considered a reference to the first occurrence in the document. (See position 12569:685)
[WARN] table-layout="fixed" and column-width unspecified => falling back to proportional-column-width(1) (See position 12605:5143)
[WARN] The following feature isn't implemented by Apache FOP, yet: table-layout="auto" (on fo:table) (See position 12966:2236)

While this level of detail is useful in debugging scenarios, I would expect it to be configurable, and not shown by default.

Note

See additional code comments in context below ↓

/cc @jelovirt & @robander

P.S. For future reference: it would be better to submit PRs from dedicated feature branches, rather than from the develop branch in your fork. This helps to isolate the proposed changes from any other changes that may land on the upstream develop branch in the meantime.)

[jyjeanne]

The PDF transformation is much noisier now, as it logs all sorts of FOP warnings:

[WARN] The contents of fo:region-body on page 1 exceed its viewport by 48187 millipoints. (See position 1:1663)
[WARN] Property ID "unique_348" (found on "fo:wrapper") previously used; ID values must be unique within a document! Any reference to it will be considered a reference to the first occurrence in the document. (See position 12569:685)
[WARN] table-layout="fixed" and column-width unspecified => falling back to proportional-column-width(1) (See position 12605:5143)
[WARN] The following feature isn't implemented by Apache FOP, yet: table-layout="auto" (on fo:table) (See position 12966:2236)

While this level of detail is useful in debugging scenarios, I would expect it to be configurable, and not shown by default.

@infotexture You're right - the FOP warnings are useful for debugging but shouldn't be displayed by
default in production builds.

I will add a showWarnings property that controls whether warnings are displayed during transformation. The default is false
to keep output clean.

[jyjeanne]

@infotexture All review comments from have been addressed.

#	Issue	Resolution
1	.chm file processing	✅ Restored doLast block
2	validateDita info messages	✅ Fixed in plugin v2.8.2
3	checkLinks peer links	✅ Fixed in plugin v2.8.2
4	FOP warnings	✅ Suppressed by default in v2.8.2 (showWarnings = false)

Best regards

[infotexture]

I'll squash this to the release branch.

Thanks for your efforts. 🙇

[infotexture]

I'll strip these unnecessary comment remnants after merging.