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.

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

Grapesgrapes 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.