entry

Pernicious Mixed Content

The content model of the entry element exhibits a nasty peculiarity that we call “pernicious mixed content”.^[3]

Every other element in DocBook contains either block elements or inline elements (including text) unambiguously. In these cases, the meaning of line breaks and spaces are well understood; they are insignificant between block elements and significant (to the SGML parser, anyway) where inline markup can occur.

Table entries are different; they can contain either block or inline elements, but not both at the same time. In other words, one entry in a table might contain a paragraph or a list while another contains simply text or another inline markup, but no single entry can contain both.

Because the content model of an entry allows both kinds of markup, each time the SGML parser encounters an entry, it has to decide what variety of markup it contains. SGML parsers are forbidden to use more than a single token of lookahead to reach this decision. In practical terms, what this means is that a line feed or space after an entry start tag causes the parser to decide that the cell contains inline markup. Subsequent discovery of a paragraph or another block element causes a parsing error.

All of these are legal:

<entry>3.1415927</entry>
<entry>General <emphasis>#PCDATA</emphasis></entry>
<entry><para>A paragraph of text
</para></entry>

However, each of these is an error:

<entry>                
Error, cannot have a line break before a block element
<para>A paragraph of text.
</para></entry>

<entry><para>A paragraph of text.
</para>               Error, cannot have a line break between block elements

<para>A paragraph of text.
</para></entry>

<entry><para>A paragraph of text.
</para>               Error, cannot have a line break after a block element

</entry>

When designing a DTD, it is wise to avoid pernicious mixed content. Unfortunately, the only way to correct the pernicious mixed content problem that already exists in DocBook is to require some sort of wrapper (a block element, or an inline like phrase) around text within table entrys. This is annoying and inconvenient in a great many tables in which text cells predominate and, in addition, differ from CALS.