<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
  <section xmlns:xi="http://www.w3.org/2001/XInclude">
   <title>Creating Tables</title>
  <para>
   DocBook tables can be quite complex, but <command>dblatex</command> should be able
   to drive most of cases thanks to the excellent newtbl implementation
   by David Hedley completely written in XSL.
  </para>
  <para>
   Here is what is supported:
  </para>
  <itemizedlist>
   <listitem>
   <para>
   Columns without specified widths (<sgmltag>colspec</sgmltag> without <sgmltag>colwidth</sgmltag> attribute) have the same size.
   </para>
  </listitem>
   <listitem>
   <para>
   A table width is always equal to the page width, if at least one column doesn't contain a fixed width attribute (e.g. colwidth=&ldquo;12cm&rdquo;).
   </para>
  </listitem>
   <listitem>
   <para>
   Fixed column widths are supported (e.g. colwidth=&ldquo;10cm&rdquo;). The
   unit can be whatever is understood by latex (e.g. cm, em, in, pt).
   </para>
  </listitem>
  <listitem>
   <para>
   Proportional column widths are supported (e.g. colwidth= &ldquo;5*&rdquo;).
   Combination of fixed and proportional width is supported too 
   (e.g. colwidth=&ldquo;5*+10cm&rdquo;).
   </para>
  </listitem>
   <listitem>
   <para>
   The <sgmltag>morerows</sgmltag> attribute of a table entry (<sgmltag>entry</sgmltag> element) is supported.
   </para>
  </listitem>
   <listitem>
   <para>
   The <sgmltag>namest</sgmltag> and <sgmltag>nameend</sgmltag> attributes of a table entry (<sgmltag>entry</sgmltag> element) are supported. It is possible to have a cell spanned on several columns.
   </para>
  </listitem>
   <listitem>
   <para>
   The <sgmltag>orient</sgmltag> table attribute is supported (portrait and landscape). 
   </para>
  </listitem>
   <listitem>
   <para>
   It is possible to have missing cell entries in a table. 
   </para>
  </listitem>
  </itemizedlist>
   <section> <title>Limitations</title>
   <para>Currently the following things are known to fail with tables:
  <itemizedlist>
   <listitem><para>program listings and screens cannot be embedded in tables.
   Some other verbatim environments like litterallayout are allowed.
   </para></listitem>
  </itemizedlist>
  <itemizedlist>
   <listitem><para>Footnotes in table cells can fail, especially if the footnote
   contains several paragraphs. Moreover they are lost is a float like a table.
   </para></listitem>
  </itemizedlist>
   </para>
   </section>
   <section>
    <title>Tables without colwidth</title>
   <para>
    When none of the <sgmltag>colspec</sgmltag> elements contains the <sgmltag>colwidth</sgmltag> attribute, all the columns have the same size, and the table width is fixed to the maximum available size. Several examples of these tables are given.
   </para>
   <xi:include href="table-eg00.xml"/>
   <xi:include href="table-eg01.xml"/>
   <xi:include href="table-eg02.xml"/>
   </section>
   <section>
    <title>Tables with mixed colspec</title>
   <para>
    A table can have <sgmltag>colspec</sgmltag> elements containing <sgmltag>colwidth</sgmltag> attribute mixed with <sgmltag>colspec</sgmltag> elements without <sgmltag>colwidth</sgmltag>. The following XML source: 
   </para>
   <programlisting>
<![CDATA[<informaltable>
  <tgroup cols="5" colsep="1" rowsep="1" align="left">
    <colspec colname="c1"/>
    <colspec align="left" colwidth="4cm"/>
    <colspec align="right" colwidth="5cm"/>
    <colspec align="center"/>
    <colspec align="center" colwidth="3cm"/>
    <tbody>
    ...
    </tbody>
  </tgroup>
</informaltable>
]]>   </programlisting>
   <para>
    is rendered like this:
   </para>
   <xi:include href="table-eg1.xml"/>
   </section>
   <section>
    <title>Tables with proportional and fixed colwidth</title>
   <para>
    Proportional column widths are supported. The following XML source:
   </para>
   <programlisting>
<![CDATA[<informaltable>
  <tgroup cols="5" colsep="1" rowsep="1" align="left"> 
    <colspec colname="c1" colwidth="*"/> 
    <colspec align="left" colwidth="2*"/> 
    <colspec align="right" colwidth="3*"/> 
    <colspec align="center"/>
    <colspec align="center" colwidth="3cm"/>
    <tbody>
    ...
    </tbody>
  </tgroup>
</informaltable>
]]>   </programlisting>
   <para>
    gives this table:
   </para>
   <xi:include href="table-eg2.xml"/>
   </section>
   <section>
    <title>Tables with fixed colwidths</title>
   <para>
    All the columns can have fixed size, like this: 
   </para>
   <programlisting>
<![CDATA[<informaltable>
  <tgroup cols="4" colsep="1" rowsep="1" align="left"> 
    <colspec colname="c1" colwidth="2cm"/> 
    <colspec align="left" colwidth="2.5cm"/> 
    <colspec align="right" colwidth="5cm"/> 
    <colspec align="center" colwidth="3cm"/>
    <tbody>
    ...
    </tbody>
  </tgroup>
</informaltable>
]]>   </programlisting>
   <para>
    It gives the following table:
   </para>
   <xi:include href="table-eg3.xml"/>
   </section>
   <section id="sec-newtbl-autowidth">
   <title>Automatic column width</title>
   <para>In the previous sections the columns widths are computed from a
   proportional basis, when no colwidth is specified or when the colwidths
   contain some star ("*"). Of course, the colwidths containing a fixed width
   incidently sets the column width with this size.</para>
   <para>It is possible to change this sizing policy by playing with the 
   <parameter>newtbl.autowidth</parameter> parameter. It can take the following
   values:
   <variablelist>
   <varlistentry><term>default</term>
   <listitem>
   <para>The automatic width (that is, latex is in charge to size the column
   width) is applied only to columns not having a specified 
   <sgmltag>colspec</sgmltag> colwidth. It includes both undefined
   <sgmltag>colspec</sgmltag>, and <sgmltag>colspec</sgmltag> without the colwidth
   attribute.</para>
   </listitem>
   </varlistentry>
   <varlistentry><term>all</term>
   <listitem>
   <para>the automatic width is applied to any column, whatever a colspec is provided
   or not.</para>
   </listitem>
   </varlistentry>
   </variablelist>
   </para>
   <para>By default the parameter is unset, and no automatic width is applied.
   Using automatic width is handy in some situations but there is no more
   control if the tables fit in the page or not, since in this case the column
   is as wide as its content, with no more paragraph breaking.</para>
   </section>
   <section>
    <title>Tables with morerows</title>
   <para>
    A table can contain entries that cover several lines. The following XML source contains an entry covering 4 lines: 
   </para>
   <programlisting>
<![CDATA[<informaltable>
  <tgroup cols="4" colsep="1" rowsep="1" align="left"> 
    <colspec colname="c1" colwidth="*"/>
    ...
    <tbody>
    <entry morerows="3">it covers 4 lines</entry>
    ...
    </tbody>
  </tgroup>
</informaltable>
]]>   </programlisting>
   <para>
    Here is an example of table containing several entries with morerows attribute:
   </para>
   <xi:include href="table-eg4.xml"/>
   </section>
   <section>
    <title>
    Landscape tables
   </title>
   <para>
    A table can be displayed in a lanscape format by using the <sgmltag>orient</sgmltag> attribute. The following XML source is an example. 
   </para>
   <programlisting>
<![CDATA[<informaltable orient="land">
  <tgroup cols="5" colsep="1" rowsep="1" align="left"> 
    <colspec colname="c1" colwidth="*"/>
    ...
    <tbody>
    ...
    </tbody>
  </tgroup>
</informaltable>
]]>   </programlisting>
   <para>
    Here is how it is displayed.
   </para>
   <xi:include href="table-land.xml"/>
   </section>
   <section>
    <title>Smaller tables</title>
   <para>
    For big tables it can be usefull to have smaller text, so that the table is not too large or too long and it can be displayed within a page. It is possible to specify smaller table text by using the <sgmltag>role</sgmltag> attribute of the elements <sgmltag>table</sgmltag> or <sgmltag>informaltable</sgmltag>.
   </para>
   <para>
    The values and the &ldquo;role&rdquo; dedicated to this attribute are specific to dblatex, but it is compliant with the DocBook specification because in general the <sgmltag>role</sgmltag> attribute purpose is never defined.
   </para>
   <para>
    The available text size definitions supported by <sgmltag>role</sgmltag> are directly taken from LaTeX:
   </para>
   <itemizedlist>
    <listitem>
    <para>
    small,
    </para>
   </listitem>
    <listitem>
    <para>
    footnotesize,
    </para>
   </listitem>
    <listitem>
    <para>
    scriptsize,
    </para>
   </listitem>
    <listitem>
    <para>
    tiny.
    </para>
   </listitem>
   </itemizedlist>
   <para>
    Here are examples for each size.
   </para>
   <xi:include href="table-small1.xml"/>
   <xi:include href="table-small2.xml"/>
   <xi:include href="table-small3.xml"/>
   <xi:include href="table-small4.xml"/>
   </section>
<section>
<title>Coloured tables</title>
<para>You can color all the table by setting its <sgmltag>bgcolor</sgmltag>
attribute.</para>
<para>You can also color only some cells by using the Processing Instruction
<literal><![CDATA[<?dblatex bgcolor="color"?>]]></literal>. The PI can apply to
columns when put in a <sgmltag>colspec</sgmltag>, to rows when put at the
beginning of a <sgmltag>row</sgmltag>, or to cells when put in a
<sgmltag>entry</sgmltag>.</para>
<para>The entry colour has precedence over the row colour,
that has precedence over the column colour, that has precedence over the table
colour.</para>
<para>The color can be expressed in hexadecimal notation like for HTML (e.g.
<literal>#C0C0C0</literal>) or in a syntax understood by the
<filename>colortbl</filename> latex package.</para>
<para>Here is an example.</para>
<xi:include href="coloured.xml"/>
<para>This table is coded like this:</para>
<programlisting><textobject><textdata
fileref="tables/coloured.xml"/></textobject></programlisting>
</section>
</section>