86 lines
No EOL
11 KiB
HTML
86 lines
No EOL
11 KiB
HTML
<!DOCTYPE html
|
|
SYSTEM "about:legacy-compat">
|
|
<html lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta charset="UTF-8"><meta name="copyright" content="(C) Copyright 2020"><meta name="generator" content="DITA-OT"><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="keywords" content=", type, , id, diagnostic messages, plug-ins, troubleshooting, troubleshooting, plug-ins, XSLT, errors, preprocessing, XSLT"><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.6</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/building-output.html">Building output</a></li><li><a href="../topics/input-formats.html">Authoring formats</a></li><li><a href="../topics/output-formats.html">Output formats</a></li><li><a href="../parameters/index.html">Parameters</a></li><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/adding-plugins.html">Adding plug-ins</a></li><li><a href="../topics/custom-plugins.html">Creating plug-ins</a><ul><li><a href="../topics/plugin-benefits.html">Plug-in benefits</a></li><li><a href="../topics/plugin-configfile.html">Plug-in descriptor file</a></li><li><a href="../topics/plugin-coding-conventions.html">Coding conventions</a></li><li><a href="../topics/plugin-dependencies.html">Plug-in dependencies</a></li><li><a href="../topics/plugin-use-cases.html">Plug-in use cases</a><ul><li><a href="../topics/plugin-set-parameters.html">Setting parameters</a></li><li><a href="../topics/plugin-anttarget.html">Adding a new Ant target</a></li><li><a href="../topics/plugin-antpreprocess.html">Adding a pre-processing step</a></li><li><a href="../topics/plugin-newtranstype.html">Adding a new output format</a></li><li><a href="../topics/plugin-xsltparams.html">Adding new parameters</a></li><li><a href="../topics/plugin-overridestyle.html">Overriding XSLT steps</a></li><li><a href="../topics/plugin-javalib.html">Adding a Java library</a></li><li class="active"><a href="../topics/plugin-messages.html">Adding new messages</a></li><li><a href="../topics/plugin-newextensions.html">New extension points</a></li><li><a href="../topics/plugin-xmlcatalog.html">Extending an XML catalog file</a></li><li><a href="../topics/plugin-rewrite-rules.html">Rewriting file names</a></li><li><a href="../topics/implement-saxon-customizations.html">Saxon customizations</a></li></ul></li><li><a href="../topics/html-customization-plugins.html">Custom HTML plug-ins</a></li><li><a href="../topics/pdf-customization-plugins.html">Custom PDF plug-ins</a></li><li><a href="../topics/globalization.html">Globalizing DITA content</a></li><li><a href="../topics/migration.html">Migrating customizations</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><messages>
|
|
<em class="ph i"><!-- See resources/messages.xml for the details. --></em>
|
|
<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>">
|
|
<reason>Message text</reason>
|
|
<response>How to resolve</response>
|
|
</message>
|
|
</messages></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><plugin id="<var class="keyword varname">plugin-id</var>">
|
|
<feature extension="dita.xsl.messages" file="<var class="keyword varname">file</var>"/>
|
|
</plugin></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><xsl:call-template name="output-message">
|
|
<xsl:with-param name="id"><var class="keyword varname">prefix</var><var class="keyword varname">number</var><var class="keyword varname">letter</var></xsl:with-param>
|
|
<xsl:with-param name="msg">Message text and parameters.</xsl:with-param>
|
|
</xsl:call-template></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-use-cases.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 use cases</a></div></div><div class="linklist reltasks"><strong>Related tasks</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/plugins-installing.html" title="Use the dita install subcommand to install plug-ins.">Installing plug-ins</a></li></ul></div><div class="linklist 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> |