Tagged tables syntax

[borisveytsman]

At the Tagging PDF workshop Ulrike and Frank asked for the syntax of tagged tables.

Here is my suggestion. The commands are either table-wide or cell-wide. Example of a table-wide commands

\begin{tabular}[headersetup=firstCol[2]]{llll}

Example of a cell-wide command

\header{(.,3-5),(8,9)} aaa & b\\

1. Table wide commands are values of a headersetup keyword. There are three of them. firstRow means that the first row is the column headers (this is the default), firstCol means that the first column is row headers, none means that the table has no headers (or all headers are defined by cell-wide commands). firstRow and firstCol may have a number n in square brackets. This means that first n rows or columns are headers. The deault is 1. The firstCol and firstRow keywords may be combined.
2. Cell-wide command \header overrides table-wide commands. It has an argument, zero or more pairs of cell coordinates in the round brackets, separated by a comma, with row number(s) first and column number(s) second. The empty argument \header{} means that the cell is not a header (possibly overriding the table-wide settings). If the argument is not empty, it specifies a range of cells for which the current cell is header, for example, (3,2-9) means third row, columns from 2 to 9 are the cells, for which the current cell is a header. The current col or row can be substituted by ., and all cells in a row or column can be substituted by - so (., -) means the current row. There could be several such ranges, which are added. together. Again, this command is only for complicated cases, not covered by headersetup

[Witiko]

Following @u-fischer's encouragement during the Thurstday Tagged PDF Workshop, I thought I would give this a try as well.

Introduction

In this post, I will go through the example tables at https://www.w3.org/WAI/tutorials/tables/ and I will propose a backwards-compatible way to represent the tables in LaTeX.

1. Tables with One Header

Example 1.1: Table with header cells in the top row only

\begin{tabular}{lll}
\colheaders Date & Event & Venue \\ \hline
12 February & Waltz with Strauss & Main Hall \\
24 March & The Obelisks & West Wing \\
14 April & The What & Main Hall \\
\end{tabular}

Here, we use the \colheaders command to indicate that the first row of the table are column headers. This should likely be the implicit behavior for tables if we ask LaTeX to figure out tagging for use.

Example 1.2: Table with header cells in the first column only

\begin{tabular}{>{\rowheader}l|ll}
Date & 12 February & 24 March & 14 April \\
Event & Waltz with Strauss & The Obelisks & The What \\
Venue & Main Hall & West Wing & Main Hall \\
\end{tabular}

Here, we use the >{\rowheader} preamble option from the array package to specify that a column contains row headers. Since the array package is part of the latex-tools bundle in the LaTeX required distribution, this should not be too controversial.

Example 1.3: Table with ambiguous data

Same approach as for Example 1.1.

2. Tables with Two Headers

Example 2.1: Table with header cells in the top row and first column

\begin{tabular}{>{\rowheader}l|lllll}
\norowheader \colheaders[2-6] & Monday & Tuesday & Wednesday & Thurstday & Friday \\ \hline
09:00--11:00 & Closed & Open   & Open   & Closed & Closed \\
11:00--13:00 & Open   & Open   & Closed & Closed & Closed \\
13:00--15:00 & Open   & Open   & Open   & Closed & Closed \\
15:00--17:00 & Closed & Closed & Closed & Open   & Open   \\
\end{tabular}

Here, we need to indicate that the upperleftmost cell is an exception and not a row or column header. For the row headers, the proposed solution expands to the \rowheader \norowheader commands, which should cancel out and have no effect. For the column headers, the proposed syntax lists a range of columns for which the current row has a header: \colheaders[2-6]. This rhymes with the \cline LaTeX command, which has a similar syntax.

Example 2.2: Table with an offset column of header cells

\begin{tabular}{l|>{\rowheader}l|llllll}
\colheaders ID & Name & July & August & September & October & November & December \\ \hline
215 & Abel & 5 & 2 & 0 & 0 & 0 & 3 \\
231 & Annette & 0 & 5 & 3 & 0 & 0 & 6 \\
173 & Bernard & 2 & 0 & 0 & 5 & 0 & 0 \\
141 & Gerald & 0 & 10 & 0 & 0 & 0 & 8 \\
99 & Michael & 8 & 8 & 8 & 8 & 0 & 4 \\
\end{tabular}

3. Tables with Irregular Headers

Example 3.1: Table with two tier headers

\begin{tabular}{>{\rowheader}l|llll}
\norowheader \colheaders[2-5] & \multicolumn{2}{l}{Mars} & \multicolumn{2}{l}{Venus} \\ \cline{2-5}
\norowheader \colheaders[2-5] & Produced & Sold & Produced & Sold \\ \hline
Teddy Bears & 50,000 & 30,000 & 100,000 & 80,000 \\
Board Games & 10,000 & 5,000  & 12,000  & 9,000  \\
\end{tabular}

Example 3.2: Table with headers spanning multiple rows or columns

\begin{tabular}{>{\rowheader}l|>{\rowheader}l|lll}
\colheaders Poster name & Color & \multicolumn{3}{l}{Sizes available} \\ \hline
\multirow[t]{3}{*}{Zodiac} & Full color & A2 & A3 & A4 \\
& Black and white & A1 & A2 & A3 \\
& Sepia & A3 & A4 & A5 \\ \cline{1-2}
\multirow[t]{3}{*}{Angels} & Black and white & A1 & A3 & A4 \\
& Sepia & A2 & A3 & A5 \\
\end{tabular}

Here, we use the \multirow command from the multirow package. The multirow package is not part of the LaTeX required distribution, so perhaps there is a better package to show multi-row cells. Regardless, the header markup in the above example would not change.

4. Tables with Multi-Level Headers

Example 4.1: Table with multiple column headers in each column

\begin{tabular}{>{\rowheader}l|ll}
\norowheader \colheaders[2-3] & Example 1 Ltd & Example 2 Co \\ \hline
Contact & James Phillips & Marie Beauchamp \\
Position & Sales Director & Sales Manager \\
Email & jp@1ltd.example.com & marie@2co.example.com \\ \hline
\norowheader \colheaders[2-3, direction=b] & Example 3 Ltd & Example 4 Inc \\ \hline
Contact & Suzette Jones & Alex Howe \\
Position & Sales Officer & Sales Director \\
Email & Suz@ltd3.example.com & howe@4inc.example.com \\
\end{tabular}

Here, we use a direction=b key of the \colheaders command to indicate that the column headers should only apply to cells below.

Example 4.2: Table with three headers related to each data cell

\begin{tabular}{>{\rowheader}l|llll}
\norowheader \colheaders[2-5] & Studio & Apt & Chalet & Villa \\ \hline
\multicolumn{5}{l}{\rowheader[direction=b] Paris} \\ \hline
1 bedroom & 11 & 20 & 25 & 23 \\
2 bedroom &    & 43 & 52 & 32 \\
3 bedroom &    & 13 & 15 & 40 \\ \hline
\multicolumn{5}{l}{\rowheader[direction=b] Rome} \\ \hline
1 bedroom & 13 & 21 & 22 & 3  \\
2 bedroom &    & 23 & 43 & 30 \\
3 bedroom &    & 16 & 32 & 40 \\
\end{tabular}

Here, we use a direction=b key of the \rowheader command to indicate that the two row headers should only apply to cells below.

Example 4.3: Split up multi-level tables

Same approach as for Example 2.1.

Conclusion

In this post, I have converted all the example tables at https://www.w3.org/WAI/tutorials/tables/ to LaTeX. Only three new commands were introduced:

• \colheaders[cols=i-j, direction=t/b] specifies that the current row contains column headers. When cols=i-j (or i-j for short) is specified, only columns i through j contain a header, otherwise all columns are expected to contain a column header. When direction=t/b is specified, the headers apply to cells above/below the header, respectively, otherwise the headers apply to cells in both directions.
• \rowheader[direction=l/r] specifies that the current cell contains a row header. When direction=l/r is specified, the header applies to cells to the left/right of the header, otherwise the header applies to cells in both directions.
• \norowheader cancels any previous \rowheader command for this cell.

Tables that are too complex to be marked up by these three commands will not be tagged.

[Witiko]

As a self-critique, this is not a very nice markup on its own, but it seems as a good option if the assignment is to have an easy-to-type way to add headers to tabular without breaking compatibility. Ideally, there would be other proposals for a nice table header markup that we could use if we didn't care about backwards compatibility. This would allow the LaTeX team to settle on a synthesis of the proposed approaches: a nice markup that is backwards-compatible.

[LupinoTech]

I'd suggest a short switch on a per-cell basis with an mandatory argument for the direction, and an optional, numeric argument for the head "level" (as positiv integer, default 0 and counting upwards).

The mandatory argument is a letter b,a,r, or l to indicate which cells are scopus of the head (all "below", "above", "to the right" and "to the left", respectively), and the optional argument indicates that the scope is valid untill another instance of this macro occurs with the same or a lower level number.

In the following table, this is examplified by the \tdh macro (unfortunately, \th is already occupied…):

\begin{tabular}{|l|l|l|l|l|}
 & \tdh{b} Studio & \thd{b} Apt & \thd{b} Chalet & \thd{b} Villa \\ \hline
\multicolumn{5}{l}{\tdh[1]{b} Paris} \\ \hline
\tdh[2]{r} 1 bedroom & 11 & 20 & 25 & 23 \\
\tdh[2]{r} 2 bedroom &    & 43 & 52 & 32 \\
\tdh[2]{r} 3 bedroom &    & 13 & 15 & 40 \\ \hline
\multicolumn{5}{l}{\tdh[1]{b} Rome} \\ \hline
\tdh[2]{r} 1 bedroom & 13 & 21 & 22 & 3  \\
\tdh[2]{r} 2 bedroom &    & 23 & 43 & 30 \\
\tdh[2]{r} 3 bedroom &    & 16 & 32 & 40 \\
\end{tabular}

In this example, the head "Paris" would count for all the cells in the next three rows of the table, because in the fourth row, contains another \tdh with the same level which "resets" the scope for that head level.

[Witiko]

This marks up the table headers, but does not seem sufficient to decide which cells a header relates to for the purpose of PDF tagging.

[LupinoTech]

i see… maybe an additional argument with the direction, like \tdh{b} for "all below untill the next \tdh", or \tdh{r} for "all cells to the right untill the next \tdh"?

[LupinoTech]

one could even add another, optional, argment to encode the heading "level". This way one could refine the mandatory argument to mean "untill the next \tdh of the same (or higher) level".

[LupinoTech]

For transparency: I adjusted the OP after the comments by @Witiko. The first draft suggested \tdh without any arguments.

[ruckertm]

Here are my considerations for tagging tables:

1. Assumptions and Consequences

   The tagging formalism must be able
   to allow arbitrary/advanced tagging schemas.
   It should be easy to use and with low overhead.
   As a consequence there should be a general purpose
   tagging schema and sets of defaults that cover the
   common cases.

   In a table there are usually more data cells than header cells.
   As a consequence the tagging should be done in the header cells.

   Each header cell has a scope: the range of other cells that it
   applies to. We can safely assume that the range of a header cell
   starts after the header cell itself, and extends either up, down,
   left or right, or any combination of these (including none of these).
   I assume further that header cells behave similar to
   sections, subsections, and subsubsections and as a consequence
   the scopes are contiguous, properly nested, and the start
   of a scope automatically ends all previous scopes
   that are on an equal or deeper nesting level (like a subsection
   ends the preceding subsection or subsubsection but not the
   preceding section.)

   As a consequence it is sufficient to specify for a header cell
   its set of directions (up, down, left, right) and its nesting
   level.

2. The general purpose tagging scheme

   A verbose tagging schema could use
   \header{, }
   Where is a non negative number where 0 is the innermost
   nesting level and higher numbers are outer nesting levels.
   One can also reserve nesting level zero for data cells, so
   that in a way all cells are headers, but a header on level 0
   naturally has only an empty scope.
   And where is a possibly empty list build from
   the keywords up, down, left, and right.

   A shorter notation could restrict the levels to 1 to 3,
   start with \h then the roman numbers i, ii, iii for the level
   and then single letters for the directions.
   For example \hiiid for \header{3, down}
   or \hilr for \header{1, left, right}

3. Convenient defaults
   To get a tagging scheme that is simple to use in most
   cases, convenient defaults are necessary to identify
   the header cells of a table without much writing.

   These defaults should identify entire rows or columns
   that contain some type of header.
   A typical example would be: the top row contains headers
   of level 1 in down direction.

   The syntax could be
   \setheader{, , , }
   where is either col or row;
   where is the number of the row or column;
   and and are as above.

   If multiple \setheader commands for the same column or the same
   row are given the later one overwrites the earlier one.
   Setting the to zero would erase the header tag.
   Multiple \setheader commands for different rows or different
   columns would be cumulative. The \setheader command for
   a column and the \setheader command for a row always overlap
   in one cell. For this cell both options, overwrite or cumulative,
   are possible. It is probably simpler to to specify that the later
   command overwrites the earlier one. It is always possible to
   overwrite the default for a cell by using a \header command
   for that cell as described above.

   As a further simplification, typical combinations of \setheader
   commands could be given as an options to the usepackage command
   loading the table tagging. For example
   \usepackage[top, left]{tagtables} would
   be equivalent to specify
   \setheader{row, 1, 1, down}
   \setheader{col, 1, 1, right}

   If \setheader commands respect the usual scoping rules of
   parameters in TeX, it is simple to redefine the tagging
   scheme of individual tables. For this purpose the special
   form \setheader{none} would be useful to erase all tagging
   specifications for the current group, before defining a new
   tagging scheme. The none keyword would also serve as an option
   when loading the package indicating that initially there are
   no default headers.