<refentry id="entry.element">
<?dbhtml filename="entry.html"?>
<refentryinfo>
<pubdate>$Date$</pubdate>
<releaseinfo>$Revision$</releaseinfo>
</refentryinfo>

<refmeta>
<indexterm><primary>elements</primary>
<secondary>entry</secondary></indexterm>
<refentrytitle>entry</refentrytitle>
<refmiscinfo>Element</refmiscinfo>
</refmeta>
<refnamediv>
<refname>entry</refname>
<refpurpose>&entry.purpose;</refpurpose>
</refnamediv>

&entry.synopsis.gen;
<refsect1 condition='ref.description'><title>Description</title>

<!-- Fragment document type declaration subset:
ArborText, Inc., 1988-1998, v.4002
<!DOCTYPE SET PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
<!ENTITY % entities SYSTEM "/Documents/books/dbnutshell/entities/entities.ent">
%entities;
]>
-->
<?Pub CX set(book(bookinfo()part()part(title()reference(title()refentry(refmeta()refnamediv()refsynopsisdiv()refsect1(title()?>
<para><sgmltag>Entry</sgmltag> is a cell in a table.</para>
<para>Each <sgmltag>Entry</sgmltag> 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 
<sgmltag>Entry</sgmltag>s with the 
<sgmltag class="attribute">MoreRows</sgmltag> attribute
from preceding rows implicitly occupy cells in the succeeding 
<sgmltag>Row</sgmltag>s.</para>
<para><sgmltag>Rows</sgmltag> 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).</para>
<sidebar id="pernicious">
<title>Pernicious Mixed Content</title>
<para>The content model of the <sgmltag>Entry</sgmltag> element exhibits a
nasty peculiarity that we call &ldquo;pernicious mixed content&rdquo;.<footnote>
<para>A term coined by Terry Allen.</para>
</footnote></para>
<para>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.</para>
<para>Table entries are different; they can contain either block or inline
elements, but not both at the same time.  In other words, one <sgmltag>Entry
</sgmltag> in a table might contain a paragraph or a list while another contains
simply &pcdata; or another inline markup, but no single <sgmltag>Entry</sgmltag>
can contain both.</para>
<para>Because the content model of an <sgmltag>Entry</sgmltag> allows both kinds
of markup, each time the &SGML; parser encounters an <sgmltag>Entry</sgmltag>,
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 <sgmltag>Entry
</sgmltag> 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.</para>
<para>All of these are legal: 
<screen>
<![CDATA[
<entry>3.1415927</entry>
<entry>General <emphasis>#PCDATA</emphasis></entry>
<entry><para>
A paragraph of text
</para></entry>
]]>
</screen>
</para>
<para>However, each of these is an error:  <screen>&lt;entry>                <lineannotation>
Error, cannot have a line break before a block element</lineannotation>
<![CDATA[<para>
A paragraph of text.
</para></entry>

<entry><para>
A paragraph of text.]]>
&lt;/para>               <lineannotation>Error, cannot have a line break between block elements
</lineannotation>
<![CDATA[<para>
A paragraph of text.
</para></entry>

]]><?ORA break="sidebar"?><![CDATA[<entry><para>
A paragraph of text.]]>
&lt;/para>               <lineannotation>Error, cannot have a line break after a block element
</lineannotation>
<![CDATA[</entry>]]></screen></para>

<para>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 <sgmltag>Phrase</sgmltag>) around &pcdata; within table
<sgmltag>Entry</sgmltag>s.  This is annoying and inconvenient in
a great many tables in which &pcdata; cells predominate and, in
addition, differ from
&CALS;.</para>
</sidebar>

<refsect2><title>Processing expectations</title>
<para>
&calssemantics;
</para>
<para>
The content of <sgmltag>Entry</sgmltag> is formatted to fit within the table
cell that it occupies.  Horizontal and vertical spanning may allow the
content of an <sgmltag>Entry</sgmltag> to occupy several physical cells.
</para>
</refsect2>

<refsect2 role='fu' revision="4.0"><title>&FutureChanges;</title>
<para>
<!--do not index this occurance-->
&fu.interfacedefinition;
</para>
</refsect2>



&entry.parents.gen;
&entry.children.gen;
</refsect1>
<refsect1 condition='ref.elem.attrdesc'><title>Attributes</title>
<variablelist>
<varlistentry><term>align</term>
<listitem>
<para>
<sgmltag class="attribute">Align</sgmltag> specifies the horizontal alignment
of text (and other elements) within the <sgmltag>Entry</sgmltag>. If no
alignment is specified, it is inherited from the <sgmltag>ColSpec</sgmltag>
for the current column, or the <sgmltag>SpanSpec</sgmltag> if this entry
occurs in a span. 
If <literal>Char</literal> is specified, see also 
<sgmltag class="attribute">Char</sgmltag> and
<sgmltag class="attribute">CharOff</sgmltag>.
</para>
</listitem>
</varlistentry>
<varlistentry><term>char</term>
<listitem>
<para>
<sgmltag class="attribute">Char</sgmltag> specifies the alignment character when
the <sgmltag class="attribute">Align</sgmltag> attribute is set to <literal>Char</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry><term>charoff</term>
<listitem>
<para>
<sgmltag class='attribute'>CharOff</sgmltag> specifies the percentage of the
column's total width that should appear to the left of the first
occurance of the character identified in <sgmltag
class='attribute'>Char</sgmltag> when the <sgmltag class='attribute'>Align</sgmltag>
attribute is set to <literal>Char</literal>. This attribute is inherited from
the relevant <sgmltag>ColSpec</sgmltag> or <sgmltag>SpanSpec</sgmltag>.
</para>
</listitem>
</varlistentry>
<varlistentry><term>colname</term>
<listitem>
<para>
<sgmltag class="attribute">ColName</sgmltag> identifies the column in which
this entry should appear; it must have been previously defined in
a <sgmltag>ColSpec</sgmltag>. <sgmltag>Entry</sgmltag>s cannot be given out of order,
the column referenced must be to the right of the last <sgmltag>Entry</sgmltag>
or <sgmltag>EntryTbl</sgmltag> placed in the current row. It is an error
to specify both a <sgmltag class="attribute">ColName</sgmltag> and a
<sgmltag class="attribute">SpanName</sgmltag>.
</para>
</listitem>
</varlistentry>
<varlistentry><term>colsep</term>
<listitem>
<para>
If <sgmltag class="attribute">ColSep</sgmltag> has the value 1 (true), then
a rule will be drawn to the right of this <sgmltag>Entry</sgmltag>.
A value of 0 (false) suppresses the rule.
The rule to the right of the last column in the table is controlled by the
<sgmltag class="attribute">Frame</sgmltag> attribute of the enclosing 
<sgmltag>Table</sgmltag> or <sgmltag>InformalTable</sgmltag> and the 
<sgmltag class="attribute">ColSep</sgmltag> of an entry in the last column in the table
is ignored. If unspecified, this attribute is inherited from the
the corresponding <sgmltag>ColSpec</sgmltag> or <sgmltag>SpanSpec</sgmltag> and
enclosing elements.
</para>
</listitem>
</varlistentry>
<varlistentry><term>morerows</term>
<listitem>
<para>
<sgmltag class="attribute">MoreRows</sgmltag> indicates how many more rows, in 
addition to the current row, this <sgmltag>Entry</sgmltag> is to occupy.
It creates a vertical span. The default of <literal>0</literal> indicates that
the <sgmltag>Entry</sgmltag> occupies only a single row.
</para>
</listitem>
</varlistentry>
<varlistentry><term>nameend</term>
<listitem>
<para>
<sgmltag class="attribute">NameEnd</sgmltag> is the name (defined in a 
<sgmltag>ColSpec</sgmltag>) of the rightmost column of a span. On <sgmltag>Entry</sgmltag>,
specifying both <sgmltag class="attribute">NameSt</sgmltag> and 
<sgmltag class="attribute">NameEnd</sgmltag> defines a horizontal span for the
current <sgmltag>Entry</sgmltag>. (See also <sgmltag class="attribute">SpanName</sgmltag>.)
</para>
</listitem>
</varlistentry>
<varlistentry><term>namest</term>
<listitem>
<para>
<sgmltag class='attribute'>NameSt</sgmltag> (<quote>name start</quote>) is the name (defined in a 
<sgmltag>ColSpec</sgmltag>) of the leftmost column of a span. On <sgmltag>Entry</sgmltag>,
specifying both <sgmltag class='attribute'>NameSt</sgmltag> and 
<sgmltag class='attribute'>NameEnd</sgmltag> defines a horizontal span for the
current <sgmltag>Entry</sgmltag>. (See also <sgmltag class='attribute'>SpanName</sgmltag>.)
</para>
</listitem>
</varlistentry>
<varlistentry><term>rotate</term>
<listitem>
<para>
If <sgmltag class="attribute">Rotate</sgmltag> has the value 1 (true), the
<sgmltag>Entry</sgmltag> 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 
<sgmltag class="attribute">Rotate</sgmltag> is ignored; they are not additive.
Only the values 0 and 1 are legal.
</para>
</listitem>
</varlistentry>
<varlistentry><term>rowsep</term>
<listitem>
<para>
If <sgmltag class="attribute">RowSep</sgmltag> has the value 1 (true), then a
rule will be drawn below the <sgmltag>Entry</sgmltag>. A value of 0 (false)
suppresses the rule. The rule below the last row in the table is
controlled by the <sgmltag class="attribute">Frame</sgmltag> attribute of the
enclosing <sgmltag>Table</sgmltag> or <sgmltag>InformalTable</sgmltag> and the
<sgmltag class="attribute">RowSep</sgmltag> of the last row is ignored. If
unspecified, this attribute is inherited from enclosing elements.
</para>
</listitem>
</varlistentry>
<varlistentry><term>spanname</term>
<listitem>
<para>
<sgmltag class="attribute">SpanName</sgmltag> is the name (defined in a 
<sgmltag>SpanSpec</sgmltag>) of a span. This cell will be rendered with the
specified horizontal span.
</para>
</listitem>
</varlistentry>
<varlistentry><term>valign</term>
<listitem>
<para>
<sgmltag class="attribute">VAlign</sgmltag> specifies the vertical alignment
of text (and other elements) within the <sgmltag>Entry</sgmltag>. If no
alignment is specified, it is inherited from enclosing elements.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 condition='ref.elem.seealso'><title>See Also</title>
&entry.seealso.gen;
</refsect1>
<refsect1><title>Examples</title>

&entry.example.seealso.gen;
</refsect1>
</refentry>

