Appendix A. Discouraged elements and attributes

Supported, unsupported, and discouraged

Not every element (tag) and attribute that works with Publican is supported. Specifically, not every tag has been tested with regards its effect on the presentation of a document once it has been built in HTML or PDF.

Publican works with almost all DocBook elements and their attributes, and most of these elements are supported. Supported elements and attributes are those whose presentation in Publican HTML and PDF output has been tested and is of an acceptable quality.

Other elements and attributes that are not known to be harmful or redundant but which have not been tested for quality are unsupported. If material within a particular DocBook tag does not look correct when you build a document in HTML or PDF, the problem could be that the transformation logic for that tag has not yet been tested. Build the document again and examine Publican's output as the document builds. Publican presents warnings about unsupported tags that it encounters in your XML files.

Finally, a small group of elements and attributes are discouraged. These elements and attributes are set out below, each accompanied by rationale explaining why it is discouraged.

Use the command $ publican print_known to print a list of tags that Publican supports, and the command publican print_banned to print a list of tags that are banned in Publican.

Section A.1. Discouraged elements

<glossdiv>

This tag set presents terms in glossaries in alphabetical order; however, the terms are sorted according to the original language of the XML, regardless of how these terms are translated into any other language. For example, a glossary produced with <glossdiv>s that looks like this in English:

A: Apple — an apple is…
G: Grapes — grapes are…
O: Orange — an orange is…
P: Peach — a peach is…

looks like this in Spanish:

A: Manzana — la manzana es…
G: Uva — la uva es…
O: Naranja — la naranja es…
P: Melocotonero — el melocotonero es…

In a translated language that does not share the same writing system with the original language in which the XML was written, the result is even more nonsensical.

<inlinegraphic>

This element presents information as a graphic rather than as text and does not provide an option to present a text alternative to the graphic. This tag therefore hides information from people with visual impairments. In jurisdictions that have legal requirements for electronic content to be accessible to people with visual impairments, documents that use this tag will not satisfy those requirements. Section 508 of the Rehabilitation Act of 1973^[4] is an example of such a requirement for federal agencies in the United States.

Note that <inlinegraphic> is not valid in DocBook version 5.

<olink>

The <olink> tag provides cross-references between XML documents. For <olink>s to work outside of documents that are all hosted within the same library of XML files, you must provide a URL for the document to which you are linking. In environments that use <olink>s, these URLs can be supplied either as an XML entity or with a server-side script. Publican does not provide any way to build or use a database for these links.

Refer to http://www.section508.gov/

Section A.2. Discouraged attributes

<[element] xreflabel="[any_string_here]">

The presence of an <xreflabel> attribute reduces the usability of printed versions of a book. As well, attribute values are not seen by translators and, consequently, cannot be translated.

For example, if you have the following:

<chapter id="ch03" xreflabel="Chapter Three">
	<title>The Secret to Eternal Life</title>
	<para>The secret to eternal life is…</para>
</chapter>

[more deathless prose here]     

…see <xref linkend="ch03"> for details.

when your XML is built to HTML, the <xref> tag becomes an HTML anchor tag as follows:

…see <a href="#ch03">Chapter Three</a> for details.

The text contained by the anchor tag is the same as the data in the <xreflabel> attribute. In this case, it means that readers of printed copies have less information available to them.

You could work around this if you make the value of the <xreflabel> attribute the same as the text within the <title></title> element tags. However, this duplication increases the risk of typo-level errors and otherwise offers no underlying improvement. And it still reduces the amount of information presented to readers of printed copies.

The following XML:

<chapter id="ch03" xreflabel="The Secret to Eternal Life">
	<title>The Secret to Eternal Life</title>
	<para>The secret to eternal life is…</para>
</chapter>

[more deathless prose here]     

…see >xref linkend="ch03"> for details.

Will result in an HTML anchor tag as follows:

…see <a href="#ch03">The Secret to Eternal Life</a> for details.

This isn't as informative as the text presented to a reader if you do not use an <xreflabel> attribute. The following:

<chapter id="ch03">
	<title>The Secret to Eternal Life</title>
	<para>The secret to eternal life is…</para>
</chapter>

[more deathless prose here]		

…see <xref linkend="ch03"> for details.

transforms the <xref> element as follows when built to HTML:

…see <a href="#ch03">Chapter 3: The Secret to Eternal Life</a> for details.

More important, however, are the translation problems that <xreflabel> tags cause. Attribute values are not seen by translators. Consequently, they are not translated. Consider the second example above again:

<chapter id="ch03" xreflabel="The Secret to Eternal Life">
	<title>The Secret to Eternal Life</title>
	<para>The secret to eternal life is…</para>
</chapter>

[more deathless prose here]		

…see <xref linkend="ch03"> for details.

In English, the <xref> is still transformed into an anchor tag as follows:

…see <a href="#ch03">The Secret to Eternal Life</a> for details.

Someone reading the German version, however, will have this as their underlying HTML:

…Sehen Sie <a href="#ch03">The Secret to Eternal Life</a> für Details.

If the <xreflabel> attribute is not used, the title and chapter indicator, both properly translated, appear to the reader. That is, the following:

<chapter id="ch03">
	<title>The Secret to Eternal Life</title>
	<para>The secret to eternal life is…</para>
</chapter>

[more deathless prose here]		

…see <xref linkend="ch03"> for details.

will, after translation, present thus to a German-speaking reader:

…Sehen Sie <a href="#ch03">Kapitel 3: Das Geheimnis des ewigen Lebens</a> für Details.

This is, not surprisingly, what we want.

The xreflabel attribute is therefore discouraged.

<[element] endterm="[any_string_here]">

The endterm attribute allows you to present hyperlinked text other than the name of the section or chapter to which the hyperlink points. As such, it decreases the usability of printed versions of documents, and causes difficulty for translators.

The text presented in an element (such as an <xref>) that contains the endterm attribute is taken from a <titleabbrev> tag in the target chapter or section. Although the content of the <titleabbrev> tag is available to translators in the document's PO files, it is removed from the context of the <xref>. The absence of this context makes reliable translation impossible in languages that mark prepositions or articles for grammatical number and grammatical gender.

For example, if you have the following:

<chapter id="The_Secret">
	<title>The Secret to Eternal Life</title>
	<titleabbrev id="final">the final chapter</titleabbrev>

	<para>The secret to eternal life is…</para>
</chapter>

[more deathless prose here]     

The solution is in <xref linkend="The_Secret" endterm="final"/>.

The text surrounding the <xref> presents in the English version of the document as:

The solution is in the final chapter.

A translator sees the <titleabbrev> in a PO file as:

#. Tag: titleabbrev
#, no-c-format
msgid "the final chapter"
msgstr ""

and sees the text that contains the <xref> elsewhere in the PO file (or, more likely, in a completely different PO file) as:

#. Tag: para
#, no-c-format
msgid "The solution is in <xref linkend=\"The_Secret\" endterm=\"final\"/>."
msgstr ""

The translator has no way of telling what will be substituted for <xref linkend="The_Secret" endterm="final"/> when the document builds, so a translation in Italian might read:

#. Tag: para
#, no-c-format
msgid "The solution is in <xref linkend=\"The_Secret\" endterm=\"final\"/>."
msgstr "La soluzione è in <xref linkend=\"The_Secret\" endterm=\"final\"/>."

Note the preposition in.

If the translator rendered the final chapter in Italian as l'ultimo capitolo, the result when the document builds will read:

La soluzione è in l'ultimo capitolo.

This result is comprehensible, but inelegant, because Italian combines some of its prepositions with its definite articles. More elegant Italian would be:

La soluzione è nell'ultimo capitolo.

Without knowing what text will appear in place of <xref linkend="The_Secret" endterm="final"/>, the translator into Italian cannot know whether to leave the preposition in to stand by itself, or which of seven different possible combinations with the definite article to use: nel, nei, nello, nell', negli, nella, or nelle.

Furthermore, note that the combined preposition and article also poses a problem with regard to whether this word should be placed in the text surrounding the <xref>, or in the <titleabbrev>. Whichever of these two solutions the translator selects will cause problems when the endterm appears in other grammatical contexts, because not all Italian prepositions can combine with the definite article in this way.

Due to the problems that endterm presents for translation, Publican discourages this attribute.