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

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

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

<para>
The <sgmltag>Table</sgmltag> element identifies a formal table.  DocBook uses the
&CALS; table model, which describes tables geometrically using rows, columns,
and cells.
</para>

<para>
Tables may include column headers and footers, but there is no provision for
row headers.
</para>

<refsect2><title>Processing expectations</title>
<para>
&format.block; &calssemantics;
</para>
</refsect2>

<refsect2 role='fu' revision="5.0"><title>&FutureChanges;</title>
<para><indexterm><primary>DocBook DTD</primary><secondary>Changes for <acronym>V5.0</acronym></secondary>
</indexterm>The
<ulink url="http://www.oasis-open.org/specs/tm9901.html">OASIS
Exchange Table Model</ulink>
will replace the full OASIS Table Model.
</para>
</refsect2>

&table.parents.gen;
&table.children.gen;
</refsect1>
<refsect1 condition='ref.elem.attrdesc'><title>Attributes</title>
<variablelist>
<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 all columns in this table.
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, not the
<sgmltag class="attribute">ColSep</sgmltag>.
</para>
</listitem>
</varlistentry>
<varlistentry><term>frame</term>
<listitem>
<para><sgmltag class="attribute">Frame</sgmltag> specifies how the table is to be framed:
</para>

<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Value</entry><entry>Meaning</entry>
</row>
</thead>
<tbody>
<row>
  <entry><sgmltag class="attvalue">all</sgmltag></entry>
  <entry><para>Frame all four sides of the table. In some environments with limited
control over table border formatting, such as HTML, this may imply additional borders.
</para></entry>
</row>
<row>
  <entry><sgmltag class="attvalue">bottom</sgmltag></entry>
  <entry><para>Frame only the bottom of the table.</para></entry>
</row>
<row>
  <entry><sgmltag class="attvalue">none</sgmltag></entry>
  <entry><para>Place no border on the table. In some environments with limited
control over table border formatting, such as HTML, this may disable other borders as
well.</para></entry>
</row>
<row>
  <entry><sgmltag class="attvalue">sides</sgmltag></entry>
  <entry><para>Frame the left and right sides of the table.</para></entry>
</row>
<row>
  <entry><sgmltag class="attvalue">top</sgmltag></entry>
  <entry><para>Frame the top of the table.</para></entry>
</row>
<row>
  <entry><sgmltag class="attvalue">topbot</sgmltag></entry>
  <entry><para>Frame the top and bottom of the table.</para></entry>
</row>
</tbody>
</tgroup>
</informaltable>

<para>There is no way to obtain a border on only the starting edge
(left, in left-to-right writing systems) of the table.</para>

</listitem>
</varlistentry>
<varlistentry><term>label</term>
<listitem>
<para>
<sgmltag class='attribute'>Label</sgmltag> specifies an identifying string for presentation purposes.
</para>
<para>
Generally, an explicit <sgmltag class='attribute'>Label</sgmltag> attribute is
used only if the processing system is incapable of generating the label
automatically. If present, the <sgmltag class='attribute'>Label</sgmltag> 
is normative; it will used even
if the processing system is capable of automatic labelling.
</para>
</listitem>
</varlistentry>
<varlistentry><term>orient</term>
<listitem>
<para>
<sgmltag class='attribute'>Orient</sgmltag> specifies the orientation of the 
<sgmltag>Table</sgmltag>. An orientation of <literal>Port</literal> is
the <quote>upright</quote>, the same orientation as the rest of the text flow.
An orientation of <literal>Land</literal> is 90 degrees counterclockwise
from the upright orientation.
</para>
</listitem>
</varlistentry>
<varlistentry><term>pgwide</term>
<listitem>
<para>
If <sgmltag class="attribute">Pgwide</sgmltag> has the value 0 (false), then the
<sgmltag>Table</sgmltag> is rendered in the current text flow (with flow
column width). A value of 1 (true) specifies that the table should be
rendered across the full text page.
</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 all the rows in the <sgmltag>Table</sgmltag>
(unless other, interior elements, suppress some or all of the rules).
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 and the <sgmltag class="attribute">RowSep</sgmltag>
of the last row is ignored.
</para>
</listitem>
</varlistentry>
<varlistentry><term>shortentry</term>
<listitem>
<para>
If <sgmltag>ShortEntry</sgmltag> has the value 1 (true), then the 
<sgmltag>Table</sgmltag>'s <sgmltag>TitleAbbrev</sgmltag> will be used in the
<sgmltag>LoT</sgmltag>, <sgmltag>Index</sgmltag>, etc. A value of 0 (false) indicates
that the full <sgmltag>Title</sgmltag> should be used in those places.
</para>
</listitem>
</varlistentry>
<varlistentry><term>tabstyle</term>
<listitem>
<para>
<sgmltag class="attribute">TabStyle</sgmltag> holds the name of a table style
defined in a stylesheet (e.g., a <acronym>FOSI</acronym>) that will be used
to process this document.
</para>
</listitem>
</varlistentry>
<varlistentry><term>tocentry</term>
<listitem>
<para>
If <sgmltag class="attribute">ToCEntry</sgmltag> has the value 1 (true), then the
<sgmltag>Table</sgmltag> will appear in a generated List of Tables.
The default value of 0 (false) indicates that it will not.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 condition='ref.elem.seealso'><title>See Also</title>
&table.seealso.gen;
</refsect1>
<refsect1><title>Examples</title>

<informalexample role="example-source">
<programlisting>&table.example.1.txt;</programlisting>
</informalexample>

<anchor id="ex.os.table.1" role="HACK-ex.out.start"/>
&table.example.1.gen;
<anchor id="ex.oe.table.1" role="HACK-ex.out.end"/>

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

