Adding new diagnostic messages

Use the dita.xsl.messages extension point to add plug-in-specific messages to the diagnostic messages that are generated by DITA-OT. These messages then can be used by any XSLT override.

Procedure

  1. Create an XML file that contains the messages that you want to add. Be sure to use the following format for the XML file: 
    <messages>
  <!-- See resources/messages.xml for the details. -->
  <message id="PrefixNumberLetter" type="Severity">
    <reason>Message text</reason>
    <response>How to resolve</response>
  </message>
</messages>
    where:
    • Prefix is a sequence of four capital letters.
      Note:
      By convention, the toolkit messages use DOTX but any sequence can be used by plug-in developers.
    • Number is a three-digit integer.
    • Letter is one of the following upper-case letters: I, W, E, or F. It should match the Severity level specified for the @type attribute.
      Note:
      As the @id attribute is used as a whole and not decomposed by recent versions of the toolkit, you could use any sequence as the message identifier. Nevertheless, to facilitate reuse of the plug-in and make it more readable by other users, we recommend following these guidelines.
    • Severity specifies the gravity of the error. It must be one of the following values:
      INFO
      Informational messages are indicated with the letter I at the end of the message ID. They highlight the progress of transformation and call attention to conditions of which you should be aware. For example, draft comments are enabled and will be rendered in the output.
      WARN
      Warnings are issued when the toolkit encounters a problem that should be corrected. Processing will continue, but the output might not be as expected. Warnings are indicated with the letter W at the end of the message ID.
      ERROR
      Error messages are issued when the toolkit encounters a more severe problem, and the output is affected. For example, some content is missing or invalid, or the content is not rendered in the output. Errors are indicated with the letter E at the end of the message ID.
      FATAL
      Fatal errors appear when the toolkit encounters a severe condition, processing stops, and no output is generated. Fatal errors are indicated with the letter F at the end of the message ID.
      Note:
      The FATAL value throws a fatal error message in XSLT and an exception in Java.
      Tip:
      If the @id attribute of your message is equal to the @id of a default DITA-OT message, your message will override the default one. An override cannot change the severity of the overridden message.
  2. Create a plugin.xml file that contains the following content: 
    <plugin id="plugin-id">
  <feature extension="dita.xsl.messages" file="file"/>
</plugin>

    where:

    • plugin-id is the plug-in identifier, for example, com.example.newmsg.
    • file is the name of the new XML file containing the messages created in step 1, for example, myMessages.xml.
  3. Use the dita install subcommand to install the plug-in.
    Note:
    For more information, see Installing plug-ins.

What to do next

Add the following call in XSLT modules to generate a message when a specific condition occurs:

<xsl:call-template name="output-message">
  <xsl:with-param name="id">prefixnumberletter</xsl:with-param>
  <xsl:with-param name="msg">Message text and parameters.</xsl:with-param>
</xsl:call-template>

You can also pass custom parameters to the template by using the @msgparams parameter. The value of @msgparams is a semicolon separated list of strings, where each token consists of a percent sign prefixed parameter index, equals sign and parameter value.

<xsl:call-template name="output-message">
  <xsl:with-param name="id">prefixnumberletter</xsl:with-param>
  <xsl:with-param name="msgparams">%1=MyFirstValue;%2=MySecondValue</xsl:with-param>
</xsl:call-template>

Use the ctx parameter if calling from a function.