doc.transformers.se_tpb_annonsator.html Maven / Gradle / Ivy
se_tpb_annonsator
Transformer documentation: se_tpb_annonsator
Transformer Purpose
The purpose of this transformer is to give a TTS the possibility to make spoken
announcements of xml structures, such as tables, notes and sidebars.
A human narrator often appends structural and/or semantic clarifications to book
elements during narration; such as appending the word "sidebar" prior to a sidebar
element, or the words "end table" at the end of a table. Such appends are here
referred to as structural announcements.
The transformer has two approaches:
-
Add attributes to the elements to announce, one for the introduction
and one for the termination of the structure.
-
Add the announcement texts to the first and last, respectively,
text nodes of the structure.
Input Requirements
The process is grammar agnostic and can be applied to any XML document.
The structure selection process supports qualified name addressing only.
The selection process does not allow selection of text nodes nor text
node substrings; the element node (singular or set) is the only allowed
return type of a selection query.
Output
On success
The input document possibly enriched with the user-defined announcement texts or attributes.
If the announcements come in the form of attributes, the document also has a
namespace declaration for the namespace of the added attributes.
On error
No specific recovery scheme. On error, this transformer will send a fatal message,
then throw an exception and abort.
Configuration/Customization
Parameters (tdf)
- input
- Input XML document
- output
- Output XML document
- overrideLang
- Override document language and use announcements from this provided
lang parameter instead.
- xslOutput
-
File used to save the produced XSLT. (This transformer does its job
by generating an XSLT and applying the transformation on the input document.
Saving the generated XSLT file is good for debug purposes, mainly.)
Extended configurability
The transformer behaviour is configured in a file according to the
input document doctype. See type.xml for that mapping.
For example, an input document declaring the doctype
"-//NISO//DTD dtbook 2005-1//EN" will make the tranformer use the
configuration file
type/dtbook-2005.xml.
As just mentioned, the transformer has two approaches to adding structural
announcements.
Which approach is used is configured in each doctype specific configuration
file. The configuration file mainly consists of rule elements, defining
which elements are being announced. Other elements are configuration of the
"add attributes"-approach, and an optional element copy containing arbitrary
xslt. The contents of copy is applied to the input document. In the dtbook-2005-1
case, the copy element contains xslt creating readable numbers for
list items in ordered lists. Basically, the transformer counts the
list items and adds a number to the beginning of the list item text node.
In the case of a list numbered with roman numerals, text can be added to each number,
such as "Roman numeral, 1". If you want the spoken announcements to appear
in lists with roman numerals, you have to edit the file adding a <xsl:when
test="lang('xx')">... where xx is your language code. You'll see
tests for lang('yy') and the easiest way is just to copy one of them,
and change the language code and the announcement text.
Configuration of the "add attributes"-approach:
- prefix
- The namespace prefix of the added announcement attributes.
- namespace
- The namespace uri of the added announcement attributes.
- attributeBefore
-
The local name of the attribute containing the introductionary
announcement text.
- attributeAfter
-
The local name of the attribute containing the terminating
announcement text.
- addAttribute
-
Whether or not to use attributes. The alternative is modifying
text nodes. The value is a lower-case boolean: true or false.
The user can select which elements that are to be announced, and for
each selection there is a rule, represented by the rule
element. Selections are made using the match
attribute's XPath value.
Each rule has one or more lang child elements, each with a
lang attribute. A lang element has two optional
child elements: before and after. The text in those
two elements is used to announce the structure that matches the rule,
before or after it. Example:
<rule match="dtb:prodnote">
<lang lang="sv">
<before>Produktionsnot.</before>
<after>Slut på produktionsnot.</after>
</lang>
<lang lang="en">
<before>Production note.</before>
<after>End of production note.</after>
</lang>
</rule>
Further development
Dependencies
Saxon 8 XSLT processor.
Author
Martin Blomberg
Licensing
LGPL