DocBook: The Definitive GuideBy Norman Walsh & Leonard Muellner
1st Edition October 1999
1-56592-580-7, Order Number: 5807
652 pages, $36.95 , Includes CD-ROM
Content Modelentry ::= (((CalloutList|GlossList|ItemizedList|OrderedList|SegmentedList| SimpleList|VariableList|Caution|Important|Note|Tip|Warning| LiteralLayout|ProgramListing|ProgramListingCO|Screen|ScreenCO| ScreenShot|FormalPara|Para|SimPara|Graphic|MediaObject)+| (#PCDATA|FootnoteRef|XRef|Abbrev|Acronym|Citation|CiteRefEntry| CiteTitle|Emphasis|FirstTerm|ForeignPhrase|GlossTerm|Footnote| Phrase|Quote|Trademark|WordAsWord|Link|OLink|ULink|Action| Application|ClassName|Command|ComputerOutput|Database|Email| EnVar|ErrorCode|ErrorName|ErrorType|Filename|Function| GUIButton|GUIIcon|GUILabel|GUIMenu|GUIMenuItem|GUISubmenu| Hardware|Interface|InterfaceDefinition|KeyCap|KeyCode|KeyCombo| KeySym|Literal|Constant|Markup|MediaLabel|MenuChoice| MouseButton|MsgText|Option|Optional|Parameter|Prompt|Property| Replaceable|ReturnValue|SGMLTag|StructField|StructName|Symbol| SystemItem|Token|Type|UserInput|VarName|Anchor|Author| AuthorInitials|CorpAuthor|ModeSpec|OtherCredit|ProductName| ProductNumber|RevHistory|Comment|Subscript|Superscript| InlineGraphic|InlineMediaObject|InlineEquation|Synopsis| CmdSynopsis|FuncSynopsis|IndexTerm)+))
rowsep NUMBER None valign
None colsep NUMBER None namest NMTOKEN None align
None rotate NUMBER None spanname NMTOKEN None nameend NMTOKEN None charoff NUTOKEN None char CDATA None morerows NUMBER None colname NMTOKEN None
The start-tag is required for this element. The end-tag is optional, if your SGML declaration allows minimization.
Entry is a cell in a table.
Each Entry may specify its starting column. Entries that do not explicitly specify a starting column begin implicitly in the column that is immediately adjacent to the preceding cell. Note that Entrys with the MoreRows attribute from preceding rows implicitly occupy cells in the succeeding Rows.
Rows are not required to be full. It is legal for some entries to be completely absent (at the beginning, middle, or end of a row).
Pernicious Mixed Content
Every other element in DocBook contains either block elements or inline elements (including #PCDATA) 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 #PCDATA 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 #PCDATA within table Entrys. This is annoying and inconvenient in a great many tables in which #PCDATA cells predominate and, in addition, differ from CALS.
The InterfaceDefinition element will be discarded in DocBook V4.0. It will no longer be available in the content model of this element.
These elements contain entry: row.
The following elements occur in entry: Abbrev, Acronym, Action, Anchor, Application, Author, AuthorInitials, CalloutList, Caution, Citation, CiteRefEntry, CiteTitle, ClassName, CmdSynopsis, Command, Comment, ComputerOutput, Constant, CorpAuthor, Database, Email, Emphasis, EnVar, ErrorCode, ErrorName, ErrorType, Filename, FirstTerm, Footnote, FootnoteRef, ForeignPhrase, FormalPara, FuncSynopsis, Function, GlossList, GlossTerm, Graphic, GUIButton, GUIIcon, GUILabel, GUIMenu, GUIMenuItem, GUISubmenu, Hardware, Important, IndexTerm, InlineEquation, InlineGraphic, InlineMediaObject, Interface, InterfaceDefinition, ItemizedList, KeyCap, KeyCode, KeyCombo, KeySym, Link, Literal, LiteralLayout, Markup, MediaLabel, MediaObject, MenuChoice, ModeSpec, MouseButton, MsgText, Note, OLink, Option, Optional, OrderedList, OtherCredit, Para, Parameter, Phrase, ProductName, ProductNumber, ProgramListing, ProgramListingCO, Prompt, Property, Quote, Replaceable, ReturnValue, RevHistory, Screen, ScreenCO, ScreenShot, SegmentedList, SGMLTag, SimPara, SimpleList, StructField, StructName, Subscript, Superscript, Symbol, Synopsis, SystemItem, Tip, Token, Trademark, Type, ULink, UserInput, VariableList, VarName, Warning, WordAsWord, XRef.
Align specifies the horizontal alignment of text (and other elements) within the Entry. If no alignment is specified, it is inherited from the ColSpec for the current column, or the SpanSpec if this entry occurs in a span. If Char is specified, see also Char and CharOff.
Char specifies the alignment character when the Align attribute is set to Char.
CharOff specifies the percentage of the column's total width that should appear to the left of the first occurance of the character identified in Char when the Align attribute is set to Char. This attribute is inherited from the relevant ColSpec or SpanSpec.
ColName identifies the column in which this entry should appear; it must have been previously defined in a ColSpec. Entrys cannot be given out of order, the column referenced must be to the right of the last Entry or EntryTbl placed in the current row. It is an error to specify both a ColName and a SpanName.
If ColSep has the value 1 (true), then a rule will be drawn to the right of this Entry. A value of 0 (false) suppresses the rule. The rule to the right of the last column in the table is controlled by the Frame attribute of the enclosing Table or InformalTable and the ColSep of an entry in the last column in the table is ignored. If unspecified, this attribute is inherited from the the corresponding ColSpec or SpanSpec and enclosing elements.
NameSt ("name start") is the name (defined in a ColSpec) of the leftmost column of a span. On Entry, specifying both NameSt and NameEnd defines a horizontal span for the current Entry. (See also SpanName.)
If Rotate has the value 1 (true), the Entry is to be rotated 90 degrees counterclockwise in the table cell. A value of 0 (false) indicates that no rotation is to occur. If the stylesheet also specifies rotation, the value of Rotate is ignored; they are not additive. Only the values 0 and 1 are legal.
If RowSep has the value 1 (true), then a rule will be drawn below the Entry. A value of 0 (false) suppresses the rule. The rule below the last row in the table is controlled by the Frame attribute of the enclosing Table or InformalTable and the RowSep of the last row is ignored. If unspecified, this attribute is inherited from enclosing elements.
SpanName is the name (defined in a SpanSpec) of a span. This cell will be rendered with the specified horizontal span.
VAlign specifies the vertical alignment of text (and other elements) within the Entry. If no alignment is specified, it is inherited from enclosing elements.
A term coined by Terry Allen.
Back to: DocBook: The Definitive Guide
© 2001, O'Reilly & Associates, Inc.