From 3eb0f640d3dbc9a8f33b3016e81e7e223de906ac Mon Sep 17 00:00:00 2001 From: Roger Sheen Date: Fri, 6 Dec 2024 22:20:10 +0100 Subject: [PATCH] Add topic on runtime configuration file: .ditaotrc Signed-off-by: Roger Sheen --- parameters/configuration-properties.dita | 4 ++- parameters/dot-ditaotrc-file.dita | 41 ++++++++++++++++++++++++ parameters/local-properties-file.dita | 3 ++ parameters/parameters.ditamap | 1 + release-notes/index.dita | 9 ++++-- resources/source-files.ditamap | 1 + 6 files changed, 55 insertions(+), 4 deletions(-) create mode 100644 parameters/dot-ditaotrc-file.dita diff --git a/parameters/configuration-properties.dita b/parameters/configuration-properties.dita index f29096fb5..db5a12ceb 100644 --- a/parameters/configuration-properties.dita +++ b/parameters/configuration-properties.dita @@ -35,6 +35,8 @@
  • Any property passed to Ant from the command line with -Dproperty or --property=
  • 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
    • @@ -43,7 +45,7 @@ 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=, or using - entries in .properties files.

    + entries in runtime configurations or .properties files.

    diff --git a/parameters/dot-ditaotrc-file.dita b/parameters/dot-ditaotrc-file.dita new file mode 100644 index 000000000..437d47b08 --- /dev/null +++ b/parameters/dot-ditaotrc-file.dita @@ -0,0 +1,41 @@ + + + + + The <filepath>.ditaotrc</filepath> configuration file + + .ditaotrc + + 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. + + + + files + .ditaotrc + .ditaotrc file + + + + +
    +

    DITA-OT now 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 + As of DITA-OT 4.2, any configurations in + local.properties files should be migrated to + .ditaotrc files. + +     +     diff --git a/parameters/local-properties-file.dita b/parameters/local-properties-file.dita index 61fb33ef9..ae3296965 100644 --- a/parameters/local-properties-file.dita +++ b/parameters/local-properties-file.dita @@ -58,6 +58,9 @@ axf.cmd=C:\\Program Files\\Antenna House\\AHFormatterV62
    This file can only be used to set Ant property values that can be passed as argument parameters to the command line. The DITA-OT Java code does not read this file. + 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.
    diff --git a/parameters/parameters.ditamap b/parameters/parameters.ditamap index 8d97ba433..01c9c9ab9 100644 --- a/parameters/parameters.ditamap +++ b/parameters/parameters.ditamap @@ -20,6 +20,7 @@ + diff --git a/release-notes/index.dita b/release-notes/index.dita index 98b75c72e..5d842ed04 100644 --- a/release-notes/index.dita +++ b/release-notes/index.dita @@ -229,9 +229,10 @@
    - New configuration file -

    A new .ditaotrc configuration file can be used to store DITA-OT runtime configurations - in multiple places.

    + New runtime configurations +

    New + .ditaotrc configuration files 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 @@ -545,6 +546,8 @@

    • +
  • +

    • For additional information on documentation issues resolved in DITA Open Toolkit Release +