source: vbox/trunk/src/libs/dita-ot-1.8.5/docsrc/dev_ref/plugin-addgeneratedtext.dita@ 99507

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN"
 "reference.dtd">
<reference id="plugin-addgeneratedtext" xml:lang="en-us">
<title>Modifying or adding generated text</title>
<shortdesc>Generated text is the term for strings that are automatically
added by the build, such as "Note" before the contents of a &lt;note>
element.</shortdesc>
<refbody>
<section><p>The generated text extension point is used to add new
strings to the default set of generated text. There are several reasons
you may want to use this:<ul>
<li>It can be used to add new text for your own processing extensions;
for example, it could be used to add localized versions of the string
"User response" to aid in rendering troubleshooting information.</li>
<li>It can be used to override the default strings in the toolkit;
for example, it could be used to reset the English string "Figure"
to "Fig".</li>
<li>It can be used to add support for new languages (for non-PDF transforms
only; PDF requires more complicated localization support). For example,
it could be used to add support for Vietnamese or Gaelic; it could
also be used to support a new variant of a previously supported language,
such as Australian English.</li>
</ul></p><dl><dlentry>
<dt><codeph>dita.xsl.strings</codeph></dt>
<dd>Add new strings to generated text file. </dd>
</dlentry></dl>       </section>
<example><title>Example: adding new strings</title><p>First copy the
file <filepath>xsl/common/strings.xml</filepath> to your plug-in,
and edit it to contain the languages that you are providing translations
for ("en-us" must be present). For this sample, copy the file into
your plug-in as <filepath>xsl/my-new-strings.xml</filepath>. The new
strings file will look something like this:</p><codeblock>&lt;?xml version="1.0" encoding="utf-8"?>
&lt;!-- Provide strings for my plug-in; this plug-in supports
     English, Icelandic, and Russian. -->
&lt;langlist>
  &lt;lang xml:lang="en"     filename="mystring-en-us.xml"/>
  &lt;lang xml:lang="en-us"  filename="mystring-en-us.xml"/>
  &lt;lang xml:lang="is"     filename="mystring-is-is.xml"/>
  &lt;lang xml:lang="is-is"  filename="mystring-is-is.xml"/>
  &lt;lang xml:lang="ru"     filename="mystring-ru-ru.xml"/>
  &lt;lang xml:lang="ru-ru"  filename="mystring-ru-ru.xml"/>
&lt;/langlist></codeblock><p>Next, copy the file <filepath>xsl/common/strings-en-us.xml</filepath> to
your plug-in, and replace the content with your own strings (be sure
to give them unique name attributes). Do the same for each language
that you are providing a translation for. For example, the file <filepath>mystring-en-us.xml</filepath> might
contain:</p><codeblock>&lt;?xml version="1.0" encoding="utf-8"?>
&lt;strings xml:lang="en-us">
  &lt;str name="String1">English generated text&lt;/str>
  &lt;str name="Another String">Another String in English&lt;/str>
&lt;/strings></codeblock><p>Use the following extension code to include
your strings in the set of generated text: </p><codeblock>&lt;plugin id="com.example.strings">
  &lt;feature extension="dita.xsl.strings" file="xsl/my-new-strings.xml"/>
&lt;/plugin></codeblock><p>The string is now available to the "getString"
template used in many DITA-OT XSLT files. For example, if processing
in a context where the xml:lang value is "en-us", the following call
would return "Another String in English":</p><codeblock>&lt;xsl:call-template name="getString">
  &lt;xsl:with-param name="stringName" select="'Another String'"/>
&lt;/xsl:call-template>
</codeblock><note>If two plug-ins define the same string, the results
will be non-deterministic, so multiple plug-ins should not try to
create the same generated text string. One common way to avoid this
problem is to ensure the name attributes used to look up the string
value are related to the ID or purpose of your plug-in.</note></example>
<example><title>Example: modifying existing strings</title><p>The
process for modifying existing generated text is exactly the same
as for adding new text, except that the strings you provide override
values that already exist. To begin, set up the <filepath>xsl/my-new-strings.xml</filepath> file
in your plug-in as in the previous example. </p><p>Next, copy the
file <filepath>xsl/common/strings-en-us.xml</filepath> to your plug-in,
and choose the strings you wish to change (be sure to leave the name
attribute unchanged, because this is the key used to look up the string).
Create a strings file for each language that needs to modify existing
strings. For example, the new file <filepath>mystring-en-us.xml</filepath> might
contain:</p><codeblock>&lt;?xml version="1.0" encoding="utf-8"?>
&lt;strings xml:lang="en-us">
  &lt;str name="Figure">Fig&lt;/str>
  &lt;str name="Draft comment">ADDRESS THIS DRAFT COMMENT&lt;/str>
&lt;/strings></codeblock><p>To integrate the new strings, use the
same method as above to add these strings to your <filepath>plugin.xml</filepath> file.
Once this plug-in is integrated, where XHTML output previously generated
the term "Figure", it will now generate "Fig"; where it previously
generated "Draft comment", it will now generate "ADDRESS THIS DRAFT
COMMENT". The same strings in other languages will not be modified
unless you also provide new versions for those languages.</p><note>If
two plug-ins override the same string in the same language, the results
will be non-deterministic (either string may be used under different
conditions). Multiple plug-ins should not override the same generated
text string for a single language.</note></example>
<example><title>Example: adding a new language</title><p>The process
for adding a new language is exactly the same as for adding new text,
except you are effectively just translating an existing strings file.
To begin, set up the <filepath>xsl/my-new-strings.xml</filepath> file
in your plug-in as in the previous examples. In this case, the only
difference is that you are adding a mapping to new languages; for
example, the following file would be used to set up support for Vietnamese:<codeblock>&lt;?xml version="1.0" encoding="utf-8"?>
&lt;!-- Map languages with xml:lang="vi" or xml:lang="vi-vn"
     to the translations in this plug-in. -->
&lt;langlist>
  &lt;lang xml:lang="vi"     filename="strings-vi.xml"/>
  &lt;lang xml:lang="vi-vn"  filename="strings-vi.xml"/>
&lt;/langlist></codeblock></p><p>Next, copy the file <filepath>xsl/common/strings-en-us.xml</filepath> to
your plug-in, and rename it to match the language you wish to add.
For example, to support Vietnamese strings you may want to pick a
name like <filepath>strings-vi.xml</filepath>. In that file, change
the <codeph>xml:lang</codeph> attribute on the root element to match
your new language.</p><p>Once the file is ready, translate the contents
of each <codeph>&lt;str></codeph> element (be sure to leave the name
attribute unchanged). Repeat this process for each new language you
wish to add.</p><p>To integrate the new languages, use the same method
as above to add these strings to your <filepath>plugin.xml</filepath> file.
Once this plug-in is integrated, non-PDF builds will include support
for Vietnamese; instead of generating the English word "Caution",
the element <codeph>&lt;note type="caution" xml:lang="vi"></codeph> may
generate something like "<term xml:lang="vi">chú ý</term>".</p><note>If
two plug-ins add support for the same language using different
values, the results will be non-deterministic (translations from either
plug-in may be picked up under different conditions).</note></example>
</refbody>
</reference>