Product SiteDocumentation Site

Disallowed elements and attributes

Supported, unsupported, and disallowed

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 4.5 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 disallowed. These elements and attributes are set out below, each accompanied by rationale explaining why it is disallowed.

A.1. Disallowed elements

<caution>, <tip>
DocBook XML supports five admonitions of varying severity: <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.
Use <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.
Publican depends on an external application, FOP, to render PDF documents. At present, FOP does not support nested tables, so attempts to build PDF files from Publican documents that contain nested tables fail.
Nested tables are therefore disallowed at least until they are supported in FOP. If you planned to include a nested table in your document, reconsider your data structure.
<glossdiv>, <glosslist>
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:
Apple — an apple is…
Grapesgrapes are…
Orange — an orange is…
Peach — a peach is…
looks like this in Spanish:
Manzana — la manzana es…
Uva — la uva es…
Naranja — la naranja es…
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.
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[3] is an example of such a requirement for federal agencies in the United States.
Note that <inlinegraphic> is not valid in DocBook version 5.
The <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.
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 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.