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.

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>
     *&lt;!-- See resources/messages.xml for the details. --&gt;*
     <message id="*Prefix**Number**Letter*" type="*error-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, F. It should match the value that is 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.

   • error-severity specifies the severity of the error. It must be one of the following values:

     • Info (I)

       Informational messages 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.

     • Warning (W)

       The toolkit encountered a problem that should be corrected. Processing will continue, but the output might not be as expected.

     • Error (E)

       The toolkit encountered 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

     • Fatal (F)

       The toolkit encountered a severe condition, processing stopped, and no output is generated.

     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.

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">*prefix**number**letter*</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">*prefix**number**letter*</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.

Related information

General extension points

Installing plug-ins