Generated text

Generated text is any text that appears in the output that was not in the original XML input file. Examples include "Chapter 5", "Example 7.2", "Table of Contents", as well as the text generated for xref cross references. The customization features for generated text, or gentext, are quite powerful. You can customize each type of generated text separately, and you can do it for any of the languages supported by DocBook.

Default generated text

If you want to see where the default generated text comes from, start by looking in the file common/en.xml included with the DocBook distribution. That file has all the text strings generated for English text. You'll notice that the common directory also has similar files for many other languages.

In the common/en.xml file, you'll see several groups of elements. The first group looks like this:

   <l:gentext key="Abstract" text="Abstract"/>
   <l:gentext key="abstract" text="Abstract"/>
   <l:gentext key="Answer" text="A:"/>
   <l:gentext key="answer" text="A:"/>
   <l:gentext key="Appendix" text="Appendix"/>
   <l:gentext key="appendix" text="appendix"/>

These l:gentext elements associate a printable string (the text attribute) with each element name (the key attribute). These gentext elements are in the l: namespace (localization) to keep them separate. The equivalent lines in the German file common/de.xml look like this:

   <l:gentext key="Abstract" text="Zusammenfassung"/>
   <l:gentext key="abstract" text="Zusammenfassung"/>
   <l:gentext key="Answer" text="A:"/>
   <l:gentext key="answer" text="A:"/>
   <l:gentext key="Appendix" text="Anhang"/>
   <l:gentext key="appendix" text="Anhang"/>

Other groups of elements are contained within a l:context element which indicates in what context those strings will be used. Here is a sample from the English title context:

   <l:context name="title">
      <l:template name="abstract" text="%t"/>
      <l:template name="answer" text="%t"/>
      <l:template name="appendix" text="Appendix %n. %t"/>

Here the text attribute value is taken to be a text template that is filled in at run time. Any %t mark in the attribute value is a placeholder for the element's title, and %n is a placeholder for its number (if it is numbered).

Customizing generated text

To customize one or more generated text strings, you create local versions of the generated text elements in your customization layer. Your collection of new generated text elements is put into a DocBook parameter named local.l10n.xml. During processing that requires generated text, that parameter is always checked before using the default values.

Following is a short customization for changing the generated text for a chapter cross reference from the default Chapter 3, Using a Mouse to something like Chapter 3: “Using a mouse” (replaces comma with colon and adds quotes around title).

Example 8.2. Customized generated text

<xsl:param name="local.l10n.xml" select="document('')"/> 1
<l:i18n xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0"> 2
  <l:l10n language="en"> 3
    <l:context name="xref-number-and-title"> 4
      <l:template name="chapter" text="Chapter %n: &#8220;%t&#8221;"/> 5
    </l:context>    
  </l:l10n>
</l:i18n>
1

Defines an XSL parameter named local.l10n.xml. The select attribute that provides the content of the parameter performs a neat trick. The XSL document() function normally opens and reads another file. But the blank function argument is a special case, which means to read the current document, that is, the current XSL file. This loads your entire customization layer file into the parameter. Once loaded, specific instances of generated text can be extracted as needed.

2

The root element for a set of generated text elements. The name i18n is short for internationalization.

3

Wrapper element for a set of generated text elements for a given language, in this case English. The name l10n is short for localization.

4

Identifies which context the contained generated text strings will be applied to. The xref-number-and-title context is used when generating text for xref cross reference elements, assuming the xref.with.number.and.title parameter hasn't been changed from its default value of one.

5

Defines a new generated text string for a given element, in this case chapter. The numerical character entities are left and right double quotes.

See the section “Customizing cross references” for a longer example.