Installing DITA Open Toolkit shows how to install the toolkit and run a
diff --git a/4.2/parameters/configuration-properties-file.html b/4.2/parameters/configuration-properties-file.html
index 353458cb..fbf4107e 100644
--- a/4.2/parameters/configuration-properties-file.html
+++ b/4.2/parameters/configuration-properties-file.html
@@ -8,7 +8,7 @@
src: 'parameters/configuration-properties-file.dita'
---
-
+
The configuration.properties file
@@ -21,6 +21,18 @@
The c
following properties are typically set in this file:
+
compatibility.keyref.treat-blank-as-empty
+
+
When set to true, this property enables a compatibility mode that processes key
+ references that contain only whitespace characters like earlier versions of DITA-OT (prior to version
+ 4.2.4). This behavior is not correct according to the DITA specification, but this setting ensures that
+ existing content that relies on this behavior will be processed in the same way as in earlier versions.
+ Set this property to false to skip these references as intended in the DITA
+ specification.
+
Warning:
This property can only be set in
+ configuration.properties.
+
+
default.cascade
Specifies the processing default value for the DITA 1.3 @cascade attribute, which
diff --git a/4.2/parameters/configuration-properties.html b/4.2/parameters/configuration-properties.html
index fb13f3b2..3ceda06c 100644
--- a/4.2/parameters/configuration-properties.html
+++ b/4.2/parameters/configuration-properties.html
@@ -9,7 +9,7 @@
src: 'parameters/configuration-properties.dita'
---
-
+
Configuration properties
@@ -22,6 +22,8 @@
Configuration properties
Any property passed to Ant from the command line with -Dproperty or
--property=value
A custom property file passed with --propertyfile
+
A .ditaotrc configuration file in the current directory or any ancestor directory, in
+ the user’s home directory, or in the root directory of the DITA-OT installation
A local.properties file in the root directory of the DITA-OT installation
The lib/org.dita.dost.platform/plugin.properties file
The configuration.properties file
@@ -30,7 +32,7 @@
Configuration properties
property are ignored.
You can use this mechanism to override DITA-OT default settings for your environment by passing parameters to
the dita command with --property=value, or using
- entries in .properties files.
+ entries in runtime configurations or .properties files.
-
Prior to DITA-OT 3.5, subcommands were specified with the double-hyphen option syntax,
- which is still supported for backwards compatibility. (For example, dita
- --install will still work.)
Arguments
@@ -196,8 +193,6 @@
Arguments and options for the <
install{ ID | URL | file }
-
- --install={ ID | URL | file }
Install a single plug-in ID from the registry at
dita-ot.org/plugins (or a local registry), from a remote URL, or a
local ZIP file.
@@ -217,9 +212,6 @@
Arguments and options for the <
install
-
- --install
-
If no ID, URL, or
file argument is provided, the installation process reloads the current set of
plug-ins from the plugins directory (or any custom locations defined via the
@@ -234,9 +226,6 @@
Arguments and options for the <
uninstallID
-
- --uninstall=ID
-
Remove the plug-in with the specified ID.
For a list of the currently installed plug-in IDs, use dita plugins.
@@ -249,18 +238,12 @@
Arguments and options for the <
plugins
-
- --plugins
-
Show a list of the currently installed plug-ins.
transtypes
-
- --transtypes
-
Show a list of the available output formats (transformation types).
The entries in this list may be passed as values to the --format argument.
@@ -268,9 +251,6 @@
Arguments and options for the <
version
-
- --version
-
Print version information and exit.
@@ -337,13 +317,17 @@
Arguments and options for the <
Print a list of available arguments, options, and subcommands.
-
+
--logfile=file
-lfile
-
Write logging messages to a file.
+
Write logging messages to a file.
+
Note:
If processing is successful, nothing is written to the log, so the file will be empty if there are no
+ errors or warnings. To include informational messages in the log, add the
+ --verbose option (or -v).
+
diff --git a/4.2/parameters/dot-ditaotrc-file.html b/4.2/parameters/dot-ditaotrc-file.html
new file mode 100644
index 00000000..d3c22b68
--- /dev/null
+++ b/4.2/parameters/dot-ditaotrc-file.html
@@ -0,0 +1,38 @@
+---
+# Generated from DITA source
+layout: 'base'
+title: 'The .ditaotrc configuration file'
+description: 'As of DITA-OT 4.2, new files can be used to store DITA-OT runtime configurations in multiple places to
+ support fine-grained configuration layers.'
+index: '../toc.html'
+src: 'parameters/dot-ditaotrc-file.dita'
+---
+
+
+
The .ditaotrc configuration file
+
+
+
+
As of DITA-OT 4.2, new files can be used to store DITA-OT runtime configurations in multiple places to
+ support fine-grained configuration layers.
+
+
DITA-OT looks for .ditaotrc configuration files in the current directory or any ancestor
+ directory first, then in the user’s home directory, and finally in the root directory of the DITA-OT
+ installation. These files are read in order and combined with the contents of the
+ local.properties file in the toolkit directory.
+
The first occurrence of a property takes precedence. This approach can be used to define multiple layers of
+ configuration, so personal defaults that apply to multiple projects can be stored in the home folder, with local
+ overrides in project folders.
+
+
For example, if the current directory includes a .ditaotrc file that sets
+
pdf.formatter=fop
and the user’s home directory has a
+ .ditaotrc file with the following content,
+
pdf.formatter=xep
+args.grammar.cache=no
DITA-OT will be run as if the following options were set on the command line:
+
--pdf.formatter=fop --args.grammar.cache=no
+
Tip:
As of DITA-OT 4.2, any configurations in
+ local.properties files should be migrated to
+ .ditaotrc files.
A local.properties file in the root directory of the DITA-OT installation can be used
to override the default values of various DITA-OT parameters.
-
For example, if you always use the same rendering engine to produce PDF output for all of your projects, you
- could create a local.properties file in the root directory of your DITA-OT installation to
- set the pdf.formatter parameter and additional options for the XSL processor:
+
Attention:
The local.properties file is still supported for backwards
+ compatibility, but as of DITA-OT 4.2, any local configurations should be migrated to
+ .ditaotrc configuration files.
+
If you always use the same rendering engine to produce PDF output for all of your projects, you could create a
+ local.properties file in the root directory of your DITA-OT installation to set the
+ pdf.formatter parameter and additional options for the XSL processor:
# Use RenderX XEP Engine for PDF output
pdf.formatter = xep
diff --git a/4.2/parameters/parameters-base.html b/4.2/parameters/parameters-base.html
index d1e76502..665cd6bb 100644
--- a/4.2/parameters/parameters-base.html
+++ b/4.2/parameters/parameters-base.html
@@ -56,13 +56,26 @@
--input.
Typically this is a DITA map, however it also can be a DITA topic if you want to transform a single
DITA file. The path can be absolute, relative to args.input.dir, or relative to the
- current directory if args.input.dir is not defined.
args.input.dir
Specifies the base directory for your documentation project.
args.output.base
Specifies the name of the output file without file extension.
args.rellinks
Specifies which links to include in the output. The following values are supported:
none – No links are included.
all – All links are included.
noparent – Ancestor and parent links are not included.
nofamily – Parent, ancestor, child, descendant, sibling, next, previous, and cousin links are not included.
+ current directory if args.input.dir is not defined.
args.input.dir
Specifies the base directory for your documentation project.
args.output.base
Specifies the name of the output file without file extension.
args.rellinks
Specifies which related
+ links to include in the output. The following values are supported:
+
+
none – No links are included.
+
all – All links are included.
+
noparent – Ancestor and parent links are not included.
+
nofamily – Parent, ancestor, child, descendant, sibling, next, previous, and cousin
+ links are not included.
+
+
For PDF output, the default value is nofamily. Other formats include all link roles
except ancestor links.
-
args.resources
Specifies resource files.
+
+
Tip:
For more precise control over related links output, set the internal Ant property
+
+ include.rellinks and specify which link roles to include.
+
args.resources
Specifies resource files.
This parameter corresponds to the command-line option
--resource.
Resource files can be used to convert partial documentation sets by processing input with additional
diff --git a/4.2/parameters/plugin-properties-file.html b/4.2/parameters/plugin-properties-file.html
index e1b81d17..ba4254c5 100644
--- a/4.2/parameters/plugin-properties-file.html
+++ b/4.2/parameters/plugin-properties-file.html
@@ -8,7 +8,7 @@
src: 'parameters/plugin-properties-file.dita'
---
-
+
diff --git a/4.2/release-notes/index.html b/4.2/release-notes/index.html
index 21738822..f784ec64 100644
--- a/4.2/release-notes/index.html
+++ b/4.2/release-notes/index.html
@@ -2,7 +2,7 @@
# Generated from DITA source
layout: 'base'
title: 'DITA Open Toolkit 4.2 Release Notes'
-description: 'DITA Open Toolkit 4.2.3 is a maintenance release that fixes issues
+description: 'DITA Open Toolkit 4.2.4 is a maintenance release that fixes issues
reported in DITA-OT 4.2, which 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.'
@@ -15,7 +15,7 @@
DITA Open Toolkit
-
DITA Open Toolkit 4.2.3 is a maintenance release that fixes issues
+
DITA Open Toolkit 4.2.4 is a maintenance release that fixes issues
reported in DITA-OT 4.2, which 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.
@@ -24,7 +24,7 @@
DITA Open Toolkit major versions may include incompatible API changes, minor versions add
functionality in a backwards-compatible manner and patch versions are maintenance releases
that include backwards-compatible bug fixes.
-
Tip:
Download the dita-ot-4.2.3.zip
+
Tip:
Download the dita-ot-4.2.4.zip
package from the project website at
dita-ot.org/download.
@@ -65,15 +65,69 @@
Requirements: Java 17
-
-
DITA-OT 4.2.3
- released May 5, 2024
+
+
DITA-OT 4.2.4
+
-
-
DITA Open Toolkit 4.2.3 is a maintenance release that includes the
+
+
DITA Open Toolkit 4.2.4 is a maintenance release that includes the
following bug fixes.
+
+
On Windows, earlier versions of the dita.bat command failed when options were
+ specified with straight quotation marks (" "). The batch script syntax has been updated to
+ enable delayed expansion, which ensures that quotation marks are parsed correctly.
+ #4525,
+ #4545
+
+
The bundled Apache Commons IO™ library has
+ been upgraded to version 2.14.0, which includes security updates to mitigate the vulnerability described in
+ CVE-2024-47554, a possible denial of service attack on untrusted input to
+ XmlStreamReader.
+ #4526
+
+
In previous releases, the HTML5 transformation did not provide a mechanism for creating HTML5
+ metadata from <data>, <data-about>, and
+ <resourceid> elements. In this release, no metadata is created for these elements
+ by default, but placeholders have been added to the getMeta processing mode to allow custom
+ plug-ins to override the placeholders and generate metadata for these elements as needed.
+ #4532,
+ #4533
+
+
Earlier versions did not generate links in HTML output when software elements such as
+ <cmdname> and <msgnum> were used in key references.
+ These elements are now processed as keywords to ensure that links are created as expected.
+ #4540,
+ #4547
+
+
Previous versions of DITA-OT incorrectly processed key references that contain only whitespace
+ characters, where the DITA specification requires them to be skipped. This bug has been fixed, but the fix
+ is not yet enabled. The incorrect behavior is retained for backwards compatibility to ensure that existing
+ content that relies on this behavior will be processed in the same way as in earlier versions.
+ A new compatibility.keyref.treat-blank-as-empty property can be set in
+ configuration.properties to switch off the incorrect
+ behavior. The fix will be enabled by default in the next minor or major version.
+ #4543,
+ #4544
+
+
The order of arguments in the dita command scripts has been adjusted to allow
+ the content of the ANT_OPTS environment variable to override CLI parameters.
+ #4545,
+ #4551
+
+
+
+
+
+
+
+
DITA-OT 4.2.3 released May 5, 2024
+
+
+
+
DITA Open Toolkit 4.2.3 is a maintenance release that includes the following bug fixes.
+
DITA-OT 4.2.2 included a regression bug that caused the map-first pre-processing routine to fail
with a NullPointerException when maps referred to topics that didn’t exist and other topics contained key
@@ -85,9 +139,9 @@
DITA-OT 4
-
-
-
DITA-OT 4.2.2
+
+
+
DITA-OT 4.2.2
released March 24, 2024
@@ -135,8 +189,8 @@
DITA-OT 4.2.2
-
-
DITA-OT 4.2.1
+
+
DITA-OT 4.2.1
released March 1, 2024
@@ -177,8 +231,8 @@
DITA-OT 4.2.1
-
-
DITA-OT 4.2
+
+
DITA-OT 4.2 released February 11, 2024
@@ -201,10 +255,11 @@
DITA-OT 4
-
New configuration file
+
New runtime configurations
-
A new .ditaotrc configuration file can be used to store DITA-OT runtime configurations
- in multiple places.
DITA-OT now looks for this file in the current directory or any ancestor directory first, then in the user’s
home directory, and finally in the root directory of the DITA-OT installation. These files are read in order
and combined with the contents of the local.properties file in the toolkit directory. The
@@ -353,7 +408,7 @@
DITA-OT 4
recommends upgrading all stylesheets to XSLT 3.0.
#4338
-
The CLI no longer uses colors when it's connected to a pipe or output is redirected to a file.
+
The CLI no longer uses colors when it’s connected to a pipe or output is redirected to a file.
#4393
Legacy table presentation classes that were deprecated in DITA-OT 2.3 have now been removed from
@@ -525,6 +580,8 @@
Building output using the Print a list of available arguments, options, and subcommands.
-
+
--logfile=file
-lfile
-
Write logging messages to a file.
+
Write logging messages to a file.
+
Note:
If processing is successful, nothing is written to the log, so the file will be empty if there are no
+ errors or warnings. To include informational messages in the log, add the
+ --verbose option (or -v).
# Use the latest DITA-OT image ↓ as parent:
-FROM ghcr.io/dita-ot/dita-ot:4.2.3
+FROM ghcr.io/dita-ot/dita-ot:4.2.4
Optional: You can extend your image with a RUN declaration that runs the dita
@@ -48,7 +48,7 @@
Installing plug-ins in a Docker
Figure 1. Sample Dockerfile with custom plug-ins: dita-ot-dir/docsrc/samples/docker/Dockerfile
# Use the latest DITA-OT image ↓ as parent:
-FROM ghcr.io/dita-ot/dita-ot:4.2.3
+FROM ghcr.io/dita-ot/dita-ot:4.2.4
# Install a custom plug-in from a remote location:
RUN dita --install https://github.com/infotexture/dita-bootstrap/archive/master.zip
@@ -66,9 +66,9 @@
Installing plug-ins in a Docker
=> => transferring dockerfile: 367B 0.0s
=> [internal] load .dockerignore 0.0s
=> => transferring context: 2B 0.0s
- => [internal] load metadata for ghcr.io/dita-ot/dita-ot:4.2.3
- => [1/3] FROM ghcr.io/dita-ot/dita-ot:4.2.3@sha256:<hash>
- => => resolve ghcr.io/dita-ot/dita-ot:4.2.3@sha256:<hash>
+ => [internal] load metadata for ghcr.io/dita-ot/dita-ot:4.2.4
+ => [1/3] FROM ghcr.io/dita-ot/dita-ot:4.2.4@sha256:<hash>
+ => => resolve ghcr.io/dita-ot/dita-ot:4.2.4@sha256:<hash>
Step 2/3 : RUN dita --install https://github.com/infotexture/dita-bootstrap/archive/master.zip
---> Running in d510f874cae0
Added net.infotexture.dita-bootstrap
diff --git a/4.2/topics/determining-version-of-ditaot.html b/4.2/topics/determining-version-of-ditaot.html
index 561228b4..79542bf3 100644
--- a/4.2/topics/determining-version-of-ditaot.html
+++ b/4.2/topics/determining-version-of-ditaot.html
@@ -23,7 +23,7 @@
Checking the DITA-OT version nu
Results
The DITA-OT version number appears on the console:
In addition to the DITA Open Toolkit documentation, there are other resources about DITA and DITA-OT that
you might find helpful.
-
diff --git a/4.2/topics/dita-ot-day-videos.html b/4.2/topics/dita-ot-day-videos.html
index ac4f41a9..e6035ab3 100644
--- a/4.2/topics/dita-ot-day-videos.html
+++ b/4.2/topics/dita-ot-day-videos.html
@@ -2,7 +2,7 @@
# Generated from DITA source
layout: 'base'
title: 'DITA-OT Day conference recordings'
-description: 'All video recordings from each DITA-OT Day conference from 2014 onward.'
+description: 'Video recordings from each DITA-OT Day conference from 2014 onward.'
index: '../toc.html'
src: 'topics/dita-ot-day-videos.dita'
---
@@ -11,7 +11,7 @@
DITA-OT Day conference recordings
-
All video recordings from each DITA-OT Day conference from 2014 onward.
+
Video recordings from each DITA-OT Day conference from 2014 onward.
Helsinki 2024 February 11, 2024 in Helsinki, Finland. DITA-OT Day was not held in 2023.
Rotterdam 2022 November 13, 2022 in Rotterdam, Netherlands. DITA-OT Day was not held in 2020 or 2021.
Brussels 2019 November 9, 2019 in Brussels, Belgium.
Rotterdam 2018 November 4, 2018 in Rotterdam, Netherlands.
Optional: Check the version of DITA-OT that is available from Homebrew:
$ brew info dita-ot
-dita-ot: stable 4.2.3
+dita-ot: stable 4.2.4
DITA Open Toolkit is an implementation of the OASIS DITA specification
https://www.dita-ot.org/
-/opt/homebrew/Cellar/dita-ot/4.2.3 (number of files, package size) *
+/opt/homebrew/Cellar/dita-ot/4.2.4 (number of files, package size) *
Poured from bottle using the formulae.brew.sh API on YYYY-MM-DD at hh:mm:ss
From: https://github.com/Homebrew/homebrew-core/blob/master/Formula/dita-ot.rb
License: Apache-2.0
@@ -63,7 +63,7 @@
Installing DITA-OT via Homebrew
Optional: Check the DITA-OT version number:
$ dita--version
-DITA-OT version 4.2.3
+DITA-OT version 4.2.4
The DITA-OT version number appears on the console.
In earlier versions of DITA-OT (2.4–3.4), use the double-hyphen option
- syntax dita
- --install. In DITA-OT 2.0–2.3, use the
- single-hyphen form: dita
- -install.
Tip:
If no ID, URL, or
file argument is provided, the installation process reloads the current set of
diff --git a/4.2/topics/plugins-removing.html b/4.2/topics/plugins-removing.html
index 981faa75..cd1a1ad3 100644
--- a/4.2/topics/plugins-removing.html
+++ b/4.2/topics/plugins-removing.html
@@ -21,11 +21,6 @@
Removing plug-ins
<plug-in-id> is the unique ID of the
plug-in, as defined in the plug-in’s configuration file (plugin.xml).
-
Note:
In earlier versions of DITA-OT (2.4–3.4), use the double-hyphen option
- syntax dita
- --uninstall. In DITA-OT 2.0–2.3, use the
- single-hyphen form: dita
- -uninstall.
Attention:
The uninstall subcommand also
removes the corresponding plug-in directory from the plugins folder.
The primary and secondary brand colors defined above are used in the examples below under
+ Setting up headers and footers and
+ Adding an image to the cover page. The theme sample also defines custom brand colors for links, note backgrounds, and
+ XML domain markup.