se/SE/stuff/dita-ot-3.3.3/docsrc/topics/plugin-messages.dita

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
<!--  This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license.  -->

<task id="plugin-messages" xml:lang="en-US">
  <title>Adding new diagnostic messages</title>
  <shortdesc>Use the <codeph>dita.xsl.messages</codeph> 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.</shortdesc>
  <prolog>
    <metadata>
      <keywords>
        <indexterm><xmlatt>type</xmlatt></indexterm>
        <indexterm><xmlatt>id</xmlatt><indexterm>diagnostic messages</indexterm></indexterm>
        <indexterm>plug-ins<indexterm>troubleshooting</indexterm></indexterm>
        <indexterm>troubleshooting<indexterm>plug-ins</indexterm></indexterm>
        <indexterm>XSLT<indexterm>errors</indexterm></indexterm>
        <indexterm>preprocessing<indexterm>XSLT</indexterm></indexterm>
      </keywords>
    </metadata>
  </prolog>
  <taskbody>
    <steps>
      <step id="step_create-message-xml">
        <cmd>Create an XML file that contains the messages that you want to add. Be sure to use the following format for
          the XML file:</cmd>
        <info><codeblock outputclass="language-xml normalize-space show-line-numbers show-whitespace">&lt;messages>
  <i>&lt;!-- See resources/messages.xml for the details. --></i>
  &lt;message id="<varname>Prefix</varname><varname>Number</varname><varname>Letter</varname>" type="<varname>error-severity</varname>">
    &lt;reason>Message text&lt;/reason>
    &lt;response>How to resolve&lt;/response>
  &lt;/message>
&lt;/messages></codeblock>where:
          <ul>
            <li><varname>Prefix</varname> is a sequence of four capital letters.<note>By convention, the toolkit
                messages use <codeph>DOTX</codeph> but any sequence can be used by plug-in developers.</note></li>
            <li><varname>Number</varname> is a three-digit integer.</li>
            <li><varname>Letter</varname> is one of the following upper-case letters: I, W, E, F. It should match the
              value that is specified for the <xmlatt>type</xmlatt> attribute.<note>As the <xmlatt>id</xmlatt> 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.</note></li>
            <li><varname>error-severity</varname> specifies the severity of the error. It must be one of the following
              values:
              <dl conkeyref="messages-push/severity-levels">
                <dlentry>
                  <dt/>
                  <dd/>
                </dlentry>
              </dl><note>The <codeph>FATAL</codeph> value throws a fatal error message in XSLT and an exception in
                Java.</note>
              <note type="tip">If the <xmlatt>id</xmlatt> attribute of your message is equal to the <xmlatt>id</xmlatt>
                of a default DITA-OT message, your message will override the default one.</note></li>
          </ul></info>
      </step>
      <step>
        <cmd>Create a <filepath>plugin.xml</filepath> file that contains the following content:</cmd>
        <info>
          <codeblock outputclass="language-xml normalize-space show-line-numbers show-whitespace">&lt;plugin id="<varname>plugin-id</varname>">
  &lt;feature extension="dita.xsl.messages" file="<varname>file</varname>"/>
&lt;/plugin></codeblock>
          <p>where:</p>
          <ul>
            <li><varname>plugin-id</varname> is the plug-in identifier, for example,
              <codeph>com.example.newmsg</codeph>.</li>
            <li><varname>file</varname> is the name of the new XML file containing the messages created in step
              <xref keyref="plugin-messages/step_create-message-xml"/>, for example,
              <filepath>myMessages.xml</filepath>. </li>
          </ul>
        </info>
      </step>
      <step>
        <cmd>Install the plug-in.</cmd>
      </step>
    </steps>
    <postreq>
      <p>Add the following call in XSLT modules to generate a message when a specific condition occurs:</p>
      <codeblock outputclass="language-xml normalize-space show-line-numbers show-whitespace">&lt;xsl:call-template name="output-message">
  &lt;xsl:with-param name="id"><varname>prefix</varname><varname>number</varname><varname>letter</varname>&lt;/xsl:with-param>
  &lt;xsl:with-param name="msg">Message text and parameters.&lt;/xsl:with-param>
&lt;/xsl:call-template></codeblock>
      <p>Use the <codeph>ctx</codeph> parameter if calling from a function.</p>
    </postreq>
  </taskbody>
</task>