Chapter 23. Tables

AsciiDoc source. 

[width="15%"]
|=======
|1 |2 |A
|3 |4 |B
|5 |6 |C
|=======

AsciiDoc source. 

.An example table
[width="50%",cols=">s,^m,e",frame="topbot",options="header,footer"]
|==========================
|      2+|Columns 2 and 3
|1       |Item 1  |Item 1
|2       |Item 2  |Item 2
|3       |Item 3  |Item 3
|4       |Item 4  |Item 4
|footer 1|footer 2|footer 3
|==========================

Short cells can be entered horizontally, longer cells vertically. The default behavior is to strip leading and trailing blank lines within a cell. These characteristics aid readability and data entry.

AsciiDoc source. 

.Windtrainer workouts
[width="80%",cols="3,^2,^2,10",options="header"]
|=========================================================
|Date |Duration |Avg HR |Notes

|22-Aug-08 |10:24 | 157 |
Worked out MSHR (max sustainable heart rate) by going hard
for this interval.

|22-Aug-08 |23:03 | 152 |
Back-to-back with previous interval.

|24-Aug-08 |40:00 | 145 |
Moderately hard interspersed with 3x 3min intervals (2min
hard + 1min really hard taking the HR up to 160).

|=========================================================

AsciiDoc source. 

[format="csv",cols="^1,4*2",options="header"]
|===================================================
ID,Customer Name,Contact Name,Customer Address,Phone
include::customers.csv[]
|===================================================

AsciiDoc source. 

[cols="e,m,^,>s",width="25%"]
|============================
|1 >s|2 |3 |4
^|5 2.2+^.^|6 .3+<.>m|7
^|8
|9 2+>|10
|============================

AsciiDoc table data can be psv, dsv or csv formatted. The default table format is psv.

AsciiDoc psv (Prefix Separated Values) and dsv (Delimiter Separated Values) formats are cell oriented — the table is treated as a sequence of cells — there are no explicit row separators.

Here are four psv cells (the second item spans two columns; the last contains an escaped separator):

|One 2+|Two and three |A \| separator character

csv is the quasi-standard row oriented Comma Separated Values (CSV) format commonly used to import and export spreadsheet and database data.

Tables can be customized by the following attributes:

Column specifiers define how columns are rendered and appear in the table cols attribute. A column specifier consists of an optional column multiplier followed by optional alignment, width and style values and is formatted like:

[<multiplier>*][<align>][<width>][<style>]

Cell specifiers allow individual cells in psv formatted tables to be spanned, multiplied, aligned and styled. Cell specifiers prefix psv | delimiters and are formatted like:

[<span>*|+][<align>][<style>]

For example, the following psv formatted cell will span two columns and the text will be centered and emphasized:

`2+^e| Cell text`

Table styles can be applied to the entire table (by setting the style attribute in the table’s attribute list) or on a per column basis (by specifying the style in the table’s cols attribute). Table data can be formatted using the following predefined styles:

AsciiDoc makes a number of attributes available to table markup templates and tags. Column specific attributes are available when substituting the colspec cell data tags.

An alternative psv separator character ! can be used (instead of |) in nested tables. This allows a single level of table nesting. Columns containing nested tables must use the asciidoc style. An example can be found in ./examples/website/newtables.txt.

Fully implementing tables is not trivial, some DocBook toolchains do better than others. AsciiDoc HTML table outputs are rendered correctly in all the popular browsers — if your DocBook generated tables don’t look right compare them with the output generated by the AsciiDoc xhtml11 backend or try a different DocBook toolchain. Here is a list of things to be aware of: