Skip to content

Commit

Permalink
Merge branch 'develop' into hotfix/2.4.3
Browse files Browse the repository at this point in the history 
* develop:
  Clarify .properties precedence cascade (Fixes #46)
  Escape backslashes in .properties (Fixes #102)
  Add topic on `local.properties` file (Fixes #81)
  Remove obsolete info, update PDF2 I18N for #46
  Document additional configuration properties #46
  Add spec links on metadata cascading
  Revise `plugin.properties` description
  • Loading branch information
@infotexture
infotexture committed Jan 28, 2017
2 parents 90a7a8f + 67a0096 commit 9f567f5
Show file tree
Hide file tree
Showing 6 changed files with 201 additions and 117 deletions.
18 changes: 18 additions & 0 deletions parameters/configuration-properties.dita
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,4 +7,22 @@
<shortdesc>The DITA-OT uses <filepath>.properties</filepath> files and internal properties that store configuration
settings for the toolkit and its plug-ins. Configuration properties are available to both Ant and Java processes,
but unlike argument properties, they cannot be set at run time.</shortdesc>
<refbody>
<section>
<p>When DITA-OT starts the Ant process, it looks for property values in the following order and locations:</p>
<ol>
<li>Any property passed to Ant from the command line with <parmname>-Dproperty</parmname> or
<parmname>--property</parmname>=<option>value</option></li>
<li>A custom property file passed with <parmname>--propertyfile</parmname></li>
<li>A <filepath>local.properties</filepath> file in the root directory of the DITA-OT installation</li>
<li>The <filepath>lib/org.dita.dost.platform/plugin.properties</filepath> file</li>
<li>The <filepath>configuration.properties</filepath> file</li>
</ol>
<p>If a given property is set in multiple places, the first value “wins” and subsequent entries for the same
property are ignored.</p>
<p>You can use this mechanism to override DITA-OT default settings for your environment by passing parameters to
the <cmdname>dita</cmdname> command with <parmname>--property</parmname>=<option>value</option>, or using
entries in <filepath>.properties</filepath> files.</p>
</section>
</refbody>
</reference>
208 changes: 94 additions & 114 deletions parameters/lib-configuration-properties.dita
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,137 +3,117 @@
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->

<reference id="configuration" xml:lang="en">
<title><filepath>configuration.properties</filepath> file</title>
<title>The <filepath>configuration.properties</filepath> file</title>
<titlealts>
<navtitle><filepath>configuration.properties</filepath></navtitle>
</titlealts>
<shortdesc>The <filepath>lib/configuration.properties</filepath> file controls certain common properties, as well as
some properties that control PDF processing.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>configuration properties
<indexterm>default.language</indexterm>
<indexterm>generate-debug-attributes</indexterm>
<indexterm>processing-mode</indexterm>
<indexterm>configuration properties <indexterm>default.language</indexterm>
<indexterm>org.dita.pdf2.i18n.enabled</indexterm>
<indexterm>org.dita.pdf2.use-out-temp</indexterm>
</indexterm>
<indexterm>files
<indexterm>lib/configuration.properties file</indexterm>
<indexterm>files <indexterm>lib/configuration.properties file</indexterm>
<indexterm>topic.fo file</indexterm>
</indexterm>
<indexterm>topic.fo
<indexterm>location of</indexterm>
<indexterm>topic.fo <indexterm>location of</indexterm>
</indexterm>
<indexterm>PDF processing
<indexterm>configuration properties</indexterm>
<indexterm>PDF processing <indexterm>configuration properties</indexterm>
</indexterm>
</keywords>
</metadata>
</prolog>
<refbody>
<section>
<fig>
<title>Properties set in the <filepath>lib/configuration.properties</filepath> file</title>
<parml>
<plentry id="default.language">
<pt><parmname>default.language</parmname></pt>
<pd id="default.language.desc">Specifies the language that is used if the input file does not have the
<xmlatt>xml:lang</xmlatt> attribute set on the root element. By default, this is set to
<option>en</option>. The allowed values are those that are defined in IETF BCP 47,
<xref href="https://tools.ietf.org/html/bcp47" format="html" scope="external">Tags for Identifying
Languages</xref>.</pd>
</plentry>
<!--<plentry id="generate-debug-attributes">
<pt><parmname>generate-debug-attributes</parmname></pt>
<pd id="generate-debug-attributes.desc">Specifies whether the @xtrf and @xtrc debugging attributes are
generated in the temporary files. The following values are allowed: <ul>
<li><option>true</option> (default) — Enables generation of debugging attributes</li>
<li><option>false</option> —Disables generation of debugging attributes</li>
</ul><note>Disabling debugging attributes reduces the size of temporary files and thus reduces memory
consumption. However, the log messages no longer have the source information available and thus the
ability to debug problems might deteriorate.</note></pd>
</plentry>
<plentry id="processing-mode">
<pt><parmname>processing-mode</parmname></pt>
<pd id="processing-mode.desc">Specifies how the DITA-OT handles errors and error recovery. The following
values are allowed:
<ul>
<li><option>strict</option> — When an error is encountered, the DITA-OT stops processing.</li>
<li><option>lax</option> (default) — When an error is encountered, the DITA-OT attempts to recover from
it.</li>
<li><option>skip</option> — When an error is encountered, the DITA continues processing but does not
attempt error recovery.</li>
</ul></pd>
</plentry>-->
<plentry id="org.dita.pdf2.i18n.enabled">
<pt><parmname>org.dita.pdf2.i18n.enabled</parmname></pt>
<pd id="org.dita.pdf2.i18n.enabled.desc">(PDF transformation only) Enables I18N font processing. The
following values are allowed:
<ul>
<li><option>true</option> (default) — Enables I18N processing</li>
<li><option>false</option> — Disables I18N processing</li>
</ul>
<draft-comment author="Kristen James Eberlein" time="16 August 2012">This needs beefing up. Here is info
provided by Jarno Elovirta:
<p>(IIRC, pre 1.0 versions of FOP didn't correctly implement font selection in XSL FO files, that's the
reason for this feature existing). The PDF2 I18N allows you to say define which characters are output
with which pseudo-font, and the font mapping files define the actual font. E.g. the configuration for
English at src/main/plugins/org.dita.pdf2/cfg/fo/i18n/en.xml
is:<codeblock>
&lt;alphabet char-set="SymbolsSuperscript">
&lt;character-set>
&lt;!-- Copyright -->
&lt;character>&amp;#169;&lt;/character>
&lt;!-- Registered Trademark -->
&lt;character>&amp;#174;&lt;/character>
&lt;!-- Trademark -->
&lt;character>&amp;#8482;&lt;/character>
&lt;!-- Service mark -->
&lt;character>&amp;#2120;&lt;/character>
&lt;/character-set>
&lt;/alphabet>
&lt;alphabet char-set="SubmenuSymbol">
&lt;character-set>
&lt;character>&amp;#x27A4;&lt;/character>
&lt;/character-set>
&lt;/alphabet>
</codeblock></p>
<p>That is, those specific characters are marked as "SymbolsSuperscript" or "SubmenuSymbol" charset. The
font mappings at src/main/plugins/org.dita.pdf2/cfg/fo/font-mappings.xml then define which font to use
for them,
e.g.:<codeblock>&lt;physical-font char-set="SymbolsSuperscript">
&lt;font-face>Helvetica, Arial Unicode MS&lt;/font-face>
&lt;baseline-shift>20%&lt;/baseline-shift>
&lt;override-size>smaller&lt;/override-size>
&lt;/physical-font></codeblock></p>
<p>The I18N processing is on by default (because it's been on before), but for most users it's just an
additional level of complexity which should be turned off and support for multiple languages be
handled in XSLT code.</p>
</draft-comment>
</pd>
</plentry>
<!--<plentry id="org.dita.pdf2.use-out-temp">
<pt><parmname>org.dita.pdf2.use-out-temp</parmname></pt>
<pd id="org.dita.pdf2.use-out-temp.desc">(PDF transformation only) Specifies whether the XSL-FO processing
writes the intermediate files (for example, the <filepath>topic.fo</filepath> file) to the output
directory. The following values are allowed:
<ul>
<li><option>true</option> — Write intermediate files to the output directory</li>
<li><option>false</option> (default) — Write intermediate files to the temporary directory</li>
</ul></pd>
</plentry>-->
<plentry id="plugindirs">
<pt><parmname>plugindirs</parmname></pt>
<pd id="plugindirs.desc">A semicolon-separated list of directory paths that the DITA-OT searches for
plug-ins to install; any relative paths are resolved against the DITA-OT base directory. Any immediate
subdirectory that contains a <filepath>plugin.xml</filepath> file is installed.</pd>
</plentry>
<plentry id="plugin.ignores">
<pt><parmname>plugin.ignores</parmname></pt>
<pd id="plugin.ignores.desc">A semicolon-separated list of directory names to be ignored during plug-in
installation; any relative paths are resolved against the DITA-OT base directory.</pd>
</plentry>
</parml>
</fig>
<p>The contents of the <filepath>configuration.properties</filepath> file are added to the DITA-OT configuration
in the <codeph>dost-configuration.jar</codeph> file when the plug-in integration process runs. The following
properties are typically set in this file:</p>
<parml>
<plentry id="otrelease-otversion">
<pt><parmname>otrelease</parmname></pt>
<pt><parmname>otversion</parmname></pt>
<pd>The DITA-OT release number and maintenance version stored here are read when version information is
requested on the commmand line via <cmdname>dita</cmdname>
<option>--version</option>.</pd>
</plentry>
<plentry id="default-cascade">
<pt><parmname>default.cascade</parmname></pt>
<pd>
<p>Specifies the processing default value for the DITA 1.3 <xmlatt>cascade</xmlatt> attribute, which
determines how map-level metadata attributes are applied to the children of elements where the attributes
are specified. DITA-OT uses the <option>merge</option> value by default for backwards compatibility with
DITA 1.2 and earlier.</p>
<note type="warning" id="protected-config-props">This property can only be set in
<filepath>configuration.properties</filepath> and should not be modified.</note></pd>
</plentry>
<plentry id="temp-file-name-scheme">
<pt><parmname>temp-file-name-scheme</parmname></pt>
<!-- org.dita.dost.module.GenMapAndTopicListModule$DefaultTempFileScheme -->
<pd>
<p>This setting specifies the name of the Java class that defines how the source URL of a topic is mapped to
the URL of the temporary file name. The current default method uses a 1:1 mapping, though future
implementations may use alternative approaches such as hashes or full absolute paths as file names.</p>
<note conref="#configuration/protected-config-props"/>
</pd>
</plentry>
<!-- DITA-OT 2.5: https://github.com/dita-ot/dita-ot/pull/2552-->
<!--
<plentry id="cli-color">
<pt><parmname>cli.color</parmname></pt>
<pd>
<p>Specifies whether the <cmdname>dita</cmdname> command prints colored output on the command line
console.</p>
<note conref="#configuration/protected-config-props"/>
</pd>
</plentry>
-->
<plentry id="plugindirs">
<pt><parmname>plugindirs</parmname></pt>
<pd id="plugindirs.desc">A semicolon-separated list of directory paths that the DITA-OT searches for plug-ins
to install; any relative paths are resolved against the DITA-OT base directory. Any immediate subdirectory
that contains a <filepath>plugin.xml</filepath> file is installed.</pd>
</plentry>
<plentry id="plugin.ignores">
<pt><parmname>plugin.ignores</parmname></pt>
<pd id="plugin.ignores.desc">A semicolon-separated list of directory names to be ignored during plug-in
installation; any relative paths are resolved against the DITA-OT base directory.</pd>
</plentry>
<plentry id="plugin-order">
<pt><parmname>plugin.order</parmname></pt>
<pd>Defines the order in which plug-ins are processed. In XML catalog files, the order of imports is
significant. If multiple plug-ins define the same thing (differently), the first catalog entry “wins”.
DITA-OT uses this property to define the order in which catalog entries are written. This mechanism is
currently used to ensure that DITA 1.3 grammar files take precedence over their DITA 1.2 equivalents.</pd>
</plentry>
<plentry id="org.dita.pdf2.i18n.enabled">
<pt><parmname>org.dita.pdf2.i18n.enabled</parmname></pt>
<pd id="org.dita.pdf2.i18n.enabled.desc">
<p>(PDF transformation only) 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).</p>
<p>When this feature is enabled, DITA-OT uses a font mapping process that takes the content language into
consideration. The mapping process uses configuration files for each language to define characters that
should be rendered with certain logical fonts, and font mappings that associate each logical font to
physical font files.</p>
<p>The following values are allowed:</p>
<ul>
<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 <xref keyref="jelovirt-on-pdf2-i18n"/>.</note>
</pd>
</plentry>
</parml>
</section>
</refbody>
<related-links>
<link keyref="dita-ot-spec-metadata-cascade"/>
<link keyref="dita-ot-spec-metadata-cascade-example"/>
<link keyref="jelovirt-on-pdf2-i18n"/>
</related-links>
</reference>
19 changes: 16 additions & 3 deletions parameters/lib-plugin-properties.dita
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,12 @@
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->

<reference id="lib-org.dita.dost.platform-plugin.properties">
<title><filepath>plugin.properties</filepath> file</title>
<title>The <filepath>plugin.properties</filepath> file</title>
<titlealts>
<navtitle><filepath>plugin.properties</filepath></navtitle>
</titlealts>
<shortdesc>The <filepath>plugin.properties</filepath> file is used to store configuration properties that are set by
the plug-in installation process. The file is located in the <filepath>lib/org.dita.dost.platform</filepath> directory; it is
regenerated each time the installation process is run and so should not be edited manually.</shortdesc>
the plug-in installation process.</shortdesc>
<prolog>
<metadata>
<keywords>
Expand All @@ -15,4 +17,15 @@
</keywords>
</metadata>
</prolog>
<refbody>
<section>
<p>The file is located in the <filepath>lib/org.dita.dost.platform</filepath> directory of the DITA-OT
installation and stores a cached version of the plug-in configuration used by the Java code.</p>
<p>The contents of this file depend on the installed plug-ins. Each plug-in may contribute properties such as the
path to the plug-in folder, supported extensions and print transformation types.</p>
<note type="warning">The <filepath>plugin.properties</filepath> file is regenerated each time the plug-in
integration process is run, so it should not be edited manually as these changes would be lost the next time a
plug-in is installed or removed.</note>
</section>
</refbody>
</reference>
45 changes: 45 additions & 0 deletions parameters/local-properties.dita
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->

<reference id="local.properties">
<title>The <filepath>local.properties</filepath> file</title>
<titlealts>
<navtitle><filepath>local.properties</filepath></navtitle>
</titlealts>
<shortdesc>A <filepath>local.properties</filepath> file in the root directory of the DITA-OT installation can be used
to override the default values of various DITA-OT parameters.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>files<indexterm>local.properties</indexterm></indexterm>
<indexterm>local.properties file</indexterm>
</keywords>
</metadata>
</prolog>
<refbody>
<example>
<p>For example, if you always use the same rendering engine to produce PDF output for all of your projects, you
could create a <filepath>local.properties</filepath> file in the root directory of your DITA-OT installation to
set the <parmname>pdf.formatter</parmname> parameter and additional options for the XSL processor:</p>
<codeblock># Use RenderX XEP Engine for PDF output
pdf.formatter = xep

# Specify the user configuration file for RenderX
custom.xep.config = /path/to/custom.config
</codeblock>
<p>Backslash “\” characters in .properties files must be escaped with a second backslash as “\\”. If you use
Antenna House Formatter on a Windows system, for example, you would set the path to the command using a
properties file entry like this:</p>
<codeblock># Use Antenna House Formatter for PDF output
pdf.formatter = ah

# Specify the path to the Antenna House Formatter command
axf.cmd=C:\\Program Files\\Antenna House\\AHFormatterV62</codeblock>
</example>
<section>
<note>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.</note>
</section>
</refbody>
</reference>
1 change: 1 addition & 0 deletions parameters/parameters.ditamap
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@
<topicref href="ant-parameters-details.dita" processing-role="resource-only" toc="no"/>
</topicref>
<topicref href="configuration-properties.dita">
<topicref href="local-properties.dita"/>
<topicref href="lib-plugin-properties.dita"/>
<topicref href="lib-configuration-properties.dita" navtitle="lib/configuration.properties file"/>
<topicref href="internal-ant-properties.dita" keys="internal-ant-properties"/>
Expand Down
Loading

0 comments on commit 9f567f5

Please sign in to comment.