Supported, unsupported, and disallowed
$
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.
<caution>
, <tip>
<tip>
, <note>
, <important>
, <caution>
, and <warning>
. Taken together, these represent a very fine-grained set of distinctions. It is unlikely that these fine distinctions can be applied consistently within a document, especially when more than one person writes or maintains the document. Moreover, this level of granularity is meaningless to readers. By design, Publican disallows the <tip>
and <caution>
elements, these elements being the two most redundant in the set.
<note>
instead of <tip>
, and use either <important>
or <warning>
instead of <caution>
. Some criteria by which you might select a suitable level of severity are presented in the ‘Document Conventions’ section of the preface of books produced with Publican's default brand.
<entrytbl>
<glossdiv>
, <glosslist>
<glossdiv>
s that looks like this in English:
Apple
— an apple is…
Grapes
— grapes are…
Orange
— an orange is…
Peach
— a peach is…
Manzana
— la manzana es…
Uva
— la uva es…
Naranja
— la naranja es…
Melocotonero
— el melocotonero es…
<inlinegraphic>
<inlinegraphic>
is not valid in DocBook version 5.
<link>
<link>
tag provides a general-purpose hyperlink and therefore offers nothing that the <xref>
and <ulink>
tags do not, for internal and external hyperlinks respectively. The <link>
tag is disallowed due to its redundancy.
<olink>
<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 produces documents intended for wide dissemination in which URLs are always necessary for cross-references. Therefore, the <olink>
tag offers no advantage over the <ulink>
tag, and is disallowed due to its redundancy.
<[element] xreflabel="[any_string_here]">
<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.
<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.
<xref>
tag becomes an HTML anchor tag as follows:
…see <a href="#ch03">Chapter Three</a> for details.
<xreflabel>
attribute. In this case, it means that readers of printed copies have less information available to them.
<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.
<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.
…see <a href="#ch03">The Secret to Eternal Life</a> for details.
<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.
<xref>
element as follows when built to HTML:
…see <a href="#ch03">Chapter 3: The Secret to Eternal Life</a> for details.
<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.
<xref>
is still transformed into an anchor tag as follows:
…see <a href="#ch03">The Secret to Eternal Life</a> for details.
…Sehen Sie <a href="#ch03">The Secret to Eternal Life</a> für Details.
<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.
…Sehen Sie <a href="#ch03">Kapitel 3: Das Geheimnis des ewigen Lebens</a> für Details.
xreflabel
attribute is therefore disallowed.
<[element] endterm="[any_string_here]">
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.
<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.
<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"/>.
<xref>
presents in the English version of the document as:
The solution is inthe final chapter
.
<titleabbrev>
in a PO file as:
#. Tag: titleabbrev #, no-c-format msgid "the final chapter" msgstr ""
<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 ""
<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"/>."
in
.
the final chapter
in Italian as l'ultimo capitolo
, the result when the document builds will read:
La soluzione è inl'ultimo capitolo
.
La soluzione è nell'ultimo capitolo
.
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
.
<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.
endterm
presents for translation, Publican disallows this attribute.