Disallowed elements and attributes

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.

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:

looks like this in Spanish:

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.