← Back to branch summary

~ubuntu-branches/ubuntu/trusty/dblatex/trusty

« back to all changes in this revision

Viewing changes to docs/table.sgml

  • Committer: Bazaar Package Importer
  • Author(s): Andreas Hoenen
  • Date: 2006-11-18 09:52:18 UTC
  • mfrom: (3.1.2 feisty)
  • Revision ID: james.westby@ubuntu.com-20061118095218-zsibrzxr9w6e2lor
Tags: 0.2-2
http://bugs.debian.org/398776
Do not depend on script mktexlsr belonging to a non-essential package
in postrm purge. (Urgency set to high due to serious severity.)
Closes: #398776

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/table.sgml
1
 
  <sect1>
2
 
   <title>
3
 
   Creating Tables
4
 
  </title>
5
 
  <para>
6
 
   DocBook tables can be quite complex, but dblatex should be able to drive most of
7
 
   cases. </para>
8
 
  <para>
9
 
   The tool contains two engines to create tables: the excellent newtbl implementation
10
 
   by David Hedley completely written in XSL, and a (obsolete) perl parser.
11
 
   One can select the engine to use with the parameter <varname>newtbl.use</varname>.
12
 
   By default the newtbl engine is used, and the perl parser will be dropped one
13
 
   day.</para>
14
 
  <para>
15
 
   Here is what is supported:
16
 
  </para>
17
 
  <itemizedlist>
18
 
   <listitem>
19
 
   <para>
20
 
   Columns without specified widths (<sgmltag>colspec</sgmltag> without <sgmltag>colwidth</sgmltag> attribute) have the same size.
21
 
   </para>
22
 
  </listitem>
23
 
   <listitem>
24
 
   <para>
25
 
   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;).
26
 
   </para>
27
 
  </listitem>
28
 
   <listitem>
29
 
   <para>
30
 
   Fixed column widths are supported (e.g. colwidth=&ldquo;10cm&rdquo;). The
31
 
   unit can be whatever is understood by latex (e.g. cm, em, in, pt).
32
 
   </para>
33
 
  </listitem>
34
 
  <listitem>
35
 
   <para>
36
 
   Proportional column widths are supported (e.g. colwidth= &ldquo;5*&rdquo;).
37
 
   Combination of fixed and proportional width is supported too 
38
 
   (e.g. colwidth=&ldquo;5*+10cm&rdquo;).
39
 
   </para>
40
 
  </listitem>
41
 
   <listitem>
42
 
   <para>
43
 
   The <sgmltag>morerows</sgmltag> attribute of a table entry (<sgmltag>entry</sgmltag> element) is supported.
44
 
   </para>
45
 
  </listitem>
46
 
   <listitem>
47
 
   <para>
48
 
   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.
49
 
   </para>
50
 
  </listitem>
51
 
   <listitem>
52
 
   <para>
53
 
   The <sgmltag>orient</sgmltag> table attribute is supported (portrait and landscape). 
54
 
   </para>
55
 
  </listitem>
56
 
   <listitem>
57
 
   <para>
58
 
   It is possible to have missing cell entries in a table. 
59
 
   </para>
60
 
  </listitem>
61
 
  </itemizedlist>
62
 
   <sect2> <title> Limitations </title>
63
 
   <para>Currently the following things are known to fail with tables:
64
 
  <itemizedlist>
65
 
   <listitem><para>Verbatim text in table cells is not
66
 
   possible.</para></listitem>
67
 
   <listitem><para>Footnotes in table cells can fail, especially if the footnote
68
 
   contains several paragraph. Moreover they are lost is a float like a table.
69
 
   </para></listitem>
70
 
  </itemizedlist>
71
 
   </para>
72
 
   </sect2>
73
 
   <sect2>
74
 
    <title>
75
 
    Tables without colwidth
76
 
   </title>
77
 
   <para>
78
 
    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.
79
 
   </para>
80
 
&table.eg00;
81
 
&table.eg01;
82
 
&table.eg02;
83
 
   </sect2>
84
 
   <sect2>
85
 
    <title>
86
 
    Tables with mixed colspec
87
 
   </title>
88
 
   <para>
89
 
    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: 
90
 
   </para>
91
 
   <programlisting>
92
 
<![CDATA[<informaltable>
93
 
  <tgroup cols="5" colsep="1" rowsep="1" align="left">
94
 
    <colspec colname="c1"/>
95
 
    <colspec align="left" colwidth="4cm"/>
96
 
    <colspec align="right" colwidth="5cm"/>
97
 
    <colspec align="center"/>
98
 
    <colspec align="center" colwidth="3cm"/>
99
 
    <tbody>
100
 
    ...
101
 
    </tbody>
102
 
  </tgroup>
103
 
</informaltable>
104
 
]]>   </programlisting>
105
 
   <para>
106
 
    is rendered like this:
107
 
   </para>
108
 
&table.eg1;
109
 
   </sect2>
110
 
   <sect2>
111
 
    <title>
112
 
    Tables with proportional and fixed colwidth
113
 
   </title>
114
 
   <para>
115
 
    Proportional column widths are supported. The following XML source:
116
 
   </para>
117
 
   <programlisting>
118
 
<![CDATA[<informaltable>
119
 
  <tgroup cols="5" colsep="1" rowsep="1" align="left"> 
120
 
    <colspec colname="c1" colwidth="*"/> 
121
 
    <colspec align="left" colwidth="2*"/> 
122
 
    <colspec align="right" colwidth="3*"/> 
123
 
    <colspec align="center"/>
124
 
    <colspec align="center" colwidth="3cm"/>
125
 
    <tbody>
126
 
    ...
127
 
    </tbody>
128
 
  </tgroup>
129
 
</informaltable>
130
 
]]>   </programlisting>
131
 
   <para>
132
 
    gives this table:
133
 
   </para>
134
 
&table.eg2;
135
 
   </sect2>
136
 
   <sect2>
137
 
    <title>
138
 
    Tables with fixed colwidths
139
 
   </title>
140
 
   <para>
141
 
    All the columns can have fixed size, like this: 
142
 
   </para>
143
 
   <programlisting>
144
 
<![CDATA[<informaltable>
145
 
  <tgroup cols="4" colsep="1" rowsep="1" align="left"> 
146
 
    <colspec colname="c1" colwidth="2cm"/> 
147
 
    <colspec align="left" colwidth="2.5cm"/> 
148
 
    <colspec align="right" colwidth="5cm"/> 
149
 
    <colspec align="center" colwidth="3cm"/>
150
 
    <tbody>
151
 
    ...
152
 
    </tbody>
153
 
  </tgroup>
154
 
</informaltable>
155
 
]]>   </programlisting>
156
 
   <para>
157
 
    It gives the following table:
158
 
   </para>
159
 
&table.eg3;
160
 
   </sect2>
161
 
   <sect2>
162
 
    <title>
163
 
    Tables with morerows
164
 
   </title>
165
 
   <para>
166
 
    A table can contain entries that cover several lines. The following XML source contains an entry covering 4 lines: 
167
 
   </para>
168
 
   <programlisting>
169
 
<![CDATA[<informaltable>
170
 
  <tgroup cols="4" colsep="1" rowsep="1" align="left"> 
171
 
    <colspec colname="c1" colwidth="*"/>
172
 
    ...
173
 
    <tbody>
174
 
    <entry morerows="3">it covers 4 lines</entry>
175
 
    ...
176
 
    </tbody>
177
 
  </tgroup>
178
 
</informaltable>
179
 
]]>   </programlisting>
180
 
   <para>
181
 
    Here is an example of table containing several entries with morerows attribute:
182
 
   </para>
183
 
&table.eg4;
184
 
   </sect2>
185
 
   <sect2>
186
 
    <title>
187
 
    Landscape tables
188
 
   </title>
189
 
   <para>
190
 
    A table can be displayed in a lanscape format by using the <sgmltag>orient</sgmltag> attribute. The following XML source is an example. 
191
 
   </para>
192
 
   <programlisting>
193
 
<![CDATA[<informaltable orient="land">
194
 
  <tgroup cols="5" colsep="1" rowsep="1" align="left"> 
195
 
    <colspec colname="c1" colwidth="*"/>
196
 
    ...
197
 
    <tbody>
198
 
    ...
199
 
    </tbody>
200
 
  </tgroup>
201
 
</informaltable>
202
 
]]>   </programlisting>
203
 
   <para>
204
 
    Here is how it is displayed.
205
 
   </para>
206
 
&table.land;
207
 
   </sect2>
208
 
   <sect2>
209
 
    <title>
210
 
    Smaller tables
211
 
   </title>
212
 
   <para>
213
 
    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>.
214
 
   </para>
215
 
   <para>
216
 
    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.
217
 
   </para>
218
 
   <para>
219
 
    The available text size definitions supported by <sgmltag>role</sgmltag> are directly taken from LaTeX:
220
 
   </para>
221
 
   <itemizedlist>
222
 
    <listitem>
223
 
    <para>
224
 
    small,
225
 
    </para>
226
 
   </listitem>
227
 
    <listitem>
228
 
    <para>
229
 
    footnotesize,
230
 
    </para>
231
 
   </listitem>
232
 
    <listitem>
233
 
    <para>
234
 
    scriptsize,
235
 
    </para>
236
 
   </listitem>
237
 
    <listitem>
238
 
    <para>
239
 
    tiny.
240
 
    </para>
241
 
   </listitem>
242
 
   </itemizedlist>
243
 
   <para>
244
 
    Here are examples for each size.
245
 
   </para>
246
 
&table.small1;
247
 
&table.small2;
248
 
&table.small3;
249
 
&table.small4;
250
 
   </sect2>
251
 
  </sect1>