bn
/
se


			
				
					
						
						
							12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485
							<!DOCTYPE html
  SYSTEM "about:legacy-compat">
<html lang="en-us"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta charset="UTF-8"><meta name="copyright" content="(C) Copyright 2019"><meta name="DC.rights.owner" content="(C) Copyright 2019"><meta name="DC.type" content="task"><meta name="description" content="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."><meta name="DC.subject" content=", type, id, diagnostic messages, plug-ins, troubleshooting, XSLT, errors, preprocessing"><meta name="keywords" content=", type, id, diagnostic messages, plug-ins, troubleshooting, XSLT, errors, preprocessing"><meta name="DC.relation" scheme="URI" content="../topics/plugin-applications.html"><meta name="DC.relation" scheme="URI" content="../extension-points/plugin-extension-points-general.html"><meta name="DC.relation" scheme="URI" content="../topics/plugins-installing.html"><meta name="DC.format" content="HTML5"><meta name="DC.identifier" content="plugin-messages"><meta name="DC.language" content="en-US"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Adding new diagnostic messages</title></head><body id="plugin-messages"><header role="banner"><div class="header">
  <p>DITA Open Toolkit</p>
  <hr>
</div></header><nav role="toc"><ul><li><a href="../index.html">DITA Open Toolkit 3.3</a></li><li><a href="../release-notes/index.html">Release Notes</a></li><li><a href="../topics/installing-client.html">Installing DITA-OT</a></li><li><a href="../topics/alternative-input-formats.html">Authoring formats</a></li><li><a href="../topics/building-output.html">Building output</a></li><li><a href="../parameters/index.html">Setting parameters</a></li><li><a href="../topics/customizing.html">Customizing DITA-OT</a><ul><li><a href="../topics/html-customization.html">Customizing HTML</a></li><li><a href="../topics/pdf-customization.html">Customizing PDF</a></li><li><a href="../topics/custom-plugins.html">Working with plug-ins</a><ul><li><a href="../topics/plugins-installing.html">Installing plug-ins</a></li><li><a href="../topics/plugins-removing.html">Removing plug-ins</a></li><li><a href="../topics/plugins-registry.html">Plug-in registry</a></li><li><a href="../topics/plugin-configfile.html">Plug-in descriptor file</a></li><li><a href="../topics/plugin-dependencies.html">Plug-in dependencies</a></li><li><a href="../topics/plugin-applications.html">Plug-in applications</a><ul><li><a href="../topics/plugin-xmlcatalog.html">Extending an XML catalog file</a></li><li><a href="../topics/plugin-anttarget.html">Adding a new target to the Ant build process</a></li><li><a href="../topics/plugin-antpreprocess.html">Adding an Ant target to the pre-processing pipeline</a></li><li><a href="../topics/plugin-newtranstype.html">Adding a new transformation type</a></li><li><a href="../topics/plugin-overridestyle.html">Overriding an XSLT-processing step</a></li><li><a href="../topics/using-plugin-URI-extension.html">Referencing files from other plug-ins</a></li><li><a href="../topics/plugin-xsltparams.html">Adding parameters to existing XSLT steps</a></li><li><a href="../topics/plugin-javalib.html">Adding a Java library to the classpath</a></li><li class="active"><a href="../topics/plugin-messages.html">Adding new diagnostic messages</a></li><li><a href="../topics/plugin-newextensions.html">Creating a new plug-in extension point</a></li><li><a href="../topics/implement-saxon-customizations.html">Adding Saxon customizations</a></li></ul></li><li><a href="../topics/plugin-sample.html">Example plugin.xml file</a></li><li><a href="../topics/plugin-best-practices.html">Best practices</a></li><li><a href="../topics/plugin-coding-conventions.html">Coding conventions</a></li></ul></li><li><a href="../extension-points/plugin-extension-points.html">Extension points</a></li><li><a href="../topics/migration.html">Migrating customizations</a></li><li><a href="../topics/globalization.html">Globalizing DITA content</a></li><li><a href="../topics/rebuilding-docs.html">Rebuilding documentation</a></li></ul></li><li><a href="../topics/troubleshooting-overview.html">Troubleshooting</a></li><li><a href="../reference/index.html">Reference</a></li><li><a href="../topics/dita-and-dita-ot-resources.html">Resources</a></li></ul></nav><main role="main"><article role="article" aria-labelledby="ariaid-title1">
  <h1 class="title topictitle1" id="ariaid-title1">Adding new diagnostic messages</h1>
  
  
  <div class="body taskbody"><p class="shortdesc">Use the <code class="ph codeph">dita.xsl.messages</code> 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.</p>
    <section><div class="tasklabel"><h2 class="sectiontitle tasklabel">Procedure</h2></div><ol class="ol steps"><li class="li step stepexpand" id="plugin-messages__step_create-message-xml">
        <span class="ph 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:</span>
        <div class="itemgroup info"><pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;messages&gt;
  <em class="ph i">&lt;!-- See resources/messages.xml for the details. --&gt;</em>
  &lt;message id="<var class="keyword varname">Prefix</var><var class="keyword varname">Number</var><var class="keyword varname">Letter</var>" type="<var class="keyword varname">error-severity</var>"&gt;
    &lt;reason&gt;Message text&lt;/reason&gt;
    &lt;response&gt;How to resolve&lt;/response&gt;
  &lt;/message&gt;
&lt;/messages&gt;</code></pre>where:
          <ul class="ul">
            <li class="li"><var class="keyword varname">Prefix</var> is a sequence of four capital letters.<div class="note note note_note"><span class="note__title">Note:</span> By convention, the toolkit
                messages use <code class="ph codeph">DOTX</code> but any sequence can be used by plug-in developers.</div></li>
            <li class="li"><var class="keyword varname">Number</var> is a three-digit integer.</li>
            <li class="li"><var class="keyword varname">Letter</var> is one of the following upper-case letters: I, W, E, F. It should match the
              value that is specified for the <code class="keyword markupname xmlatt">@type</code> attribute.<div class="note note note_note"><span class="note__title">Note:</span> As the <code class="keyword markupname xmlatt">@id</code> 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.</div></li>
            <li class="li"><var class="keyword varname">error-severity</var> specifies the severity of the error. It must be one of the following
              values:
              <dl class="dl">
        
          <dt class="dt dlterm">Info (I)</dt>
          <dd class="dd">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.</dd>
        
        
          <dt class="dt dlterm">Warning (W)</dt>
          <dd class="dd">The toolkit encountered a problem that should be corrected. Processing will continue, but the output might
            not be as expected.</dd>
        
        
          <dt class="dt dlterm">Error (E)</dt>
          <dd class="dd">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</dd>
        
        
          <dt class="dt dlterm">Fatal (F)</dt>
          <dd class="dd">The toolkit encountered a severe condition, processing stopped, and no output is generated.</dd>
        
      </dl><div class="note note note_note"><span class="note__title">Note:</span> The <code class="ph codeph">FATAL</code> value throws a fatal error message in XSLT and an exception in
                Java.</div>
              <div class="note tip note_tip"><span class="note__title">Tip:</span> If the <code class="keyword markupname xmlatt">@id</code> attribute of your message is equal to the <code class="keyword markupname xmlatt">@id</code>
                of a default DITA-OT message, your message will override the default one.</div></li>
          </ul></div>
      </li><li class="li step stepexpand">
        <span class="ph cmd">Create a <span class="ph filepath">plugin.xml</span> file that contains the following content:</span>
        <div class="itemgroup info">
          <pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;plugin id="<var class="keyword varname">plugin-id</var>"&gt;
  &lt;feature extension="dita.xsl.messages" file="<var class="keyword varname">file</var>"/&gt;
&lt;/plugin&gt;</code></pre>
          <p class="p">where:</p>
          <ul class="ul">
            <li class="li"><var class="keyword varname">plugin-id</var> is the plug-in identifier, for example,
              <code class="ph codeph">com.example.newmsg</code>.</li>
            <li class="li"><var class="keyword varname">file</var> is the name of the new XML file containing the messages created in step
              <a class="xref" href="plugin-messages.html#plugin-messages__step_create-message-xml">1</a>, for example,
              <span class="ph filepath">myMessages.xml</span>. </li>
          </ul>
        </div>
      </li><li class="li step stepexpand">
        <span class="ph cmd">Install the plug-in.</span>
      </li></ol></section>
    <section class="section postreq"><div class="tasklabel"><h2 class="sectiontitle tasklabel">What to do next</h2></div>
      <p class="p">Add the following call in XSLT modules to generate a message when a specific condition occurs:</p>
      <pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code>&lt;xsl:call-template name="output-message"&gt;
  &lt;xsl:with-param name="id"&gt;<var class="keyword varname">prefix</var><var class="keyword varname">number</var><var class="keyword varname">letter</var>&lt;/xsl:with-param&gt;
  &lt;xsl:with-param name="msg"&gt;Message text and parameters.&lt;/xsl:with-param&gt;
&lt;/xsl:call-template&gt;</code></pre>
      <p class="p">Use the <code class="ph codeph">ctx</code> parameter if calling from a function.</p>
    </section>
  </div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/plugin-applications.html" title="Plug-ins allow you to extend the functionality of DITA-OT. This might entail adding support for specialized document types, integrating processing overrides, or defining new output transformations.">Plug-in applications</a></div></div><div class="linklist relinfo reltasks"><strong>Related tasks</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/plugins-installing.html" title="Use the dita command to install a plug-in.">Installing plug-ins</a></li></ul></div><div class="linklist relinfo relref"><strong>Related reference</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../extension-points/plugin-extension-points-general.html" title="These extension points enable you to extend DITA-OT. You can add Ant targets or imports; add a Java library to the classpath parameter; add a new transformation type; extend a catalog file; add new diagnostic messages, and more.">General extension points</a></li></ul></div></nav></article></main></body></html>