[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: DocBook Publishers schema v1.1 rev 0.4 for review
| Folks, please find attached rev0.4, which updates the rowheader verbiage from Nathalie and includes RFE 3560731: Add stage direction markup Please review and comment on the locations that stagedir and inlinestagedir should be allowed. We will meet this week, so I'll update the OASIS calendar shortly. Also, did we decide if the additional documentation from Nathalie should be included as an appendix? I do not remember the decision, but have included it here for your reference (but not in the draft). |
Attachment:
publishers-v1.1-csd01.pdf
Description: Adobe PDF document
Attachment:
publishers-v1.1-csd01.xml
Description: application/xml
<?xml version="1.0" encoding="UTF-8"?>
<?oxygen RNGSchema="http://docbook.org/xml/5.1b8/rng/docbook.rng"; type="xml"?>
<?xml-stylesheet type="text/css" href="docbook5.1.css"?>
<article xmlns="http://docbook.org/ns/docbook";
xmlns:xlink="http://www.w3.org/1999/xlink"; version="5.1b8"
audience="main"
xml:lang="de">
<info>
<title>CALS Table Accessibility in docBook 5.1</title>
<author>
<personname>Nathalie Sequeira</personname>
</author>
<date>2013-02-22</date>
<abstract>
<para>Usage guide to the expanded CALS table model in DocBook 5.1, with notes for
documentation changes to enhance its usability.</para>
</abstract>
</info>
<section>
<title>Walk-through by example</title>
<para>In marking up a CALS table for screen reader accessibility (in HTML output), there
are two steps to be taken, depending on the table structure's complexity:</para>
<orderedlist>
<listitem>
<para>identify the table's headers</para>
</listitem>
<listitem>
<para>explicitly associate table data with its headers</para>
</listitem>
</orderedlist>
<section>
<title>Identify the table's headers</title>
<para>In very simple tables with only one row or column of headers, this mechanism alone
is sufficient to allow screen readers to accociate data with its respective
headers.</para>
<section>
<title>Identify column headers</title>
<para>To identify column headers, the relevant rows are wrapped in the
<code>thead</code> element.</para>
<table frame="all">
<title>example: a simple table with column headers</title>
<tgroup cols="3">
<thead>
<row>
<entry>Mark's points</entry>
<entry>Peter's points</entry>
<entry>Cindy's points</entry>
</row>
</thead>
<tbody>
<row>
<entry>11,123.45</entry>
<entry>11,012.34</entry>
<entry>10,987.64</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section>
<title>Identify row headers</title>
<para>DocBook currently offers two alternatives to identify row headers:</para>
<itemizedlist>
<listitem>
<para>if only the first column contains row headers, set the
<code>rowheader</code> attribute to the <code>firstcol</code> value
in the <code>table</code> element.</para>
<table frame="all" rowheader="firstcol">
<title>example: a simple table with first row headers</title>
<tgroup cols="2">
<tbody>
<row>
<entry>Mark's points</entry>
<entry>11,123.45</entry>
</row>
<row>
<entry>Peter's points</entry>
<entry>11,012.34</entry>
</row>
<row>
<entry>Cindy's points</entry>
<entry>10,987.64</entry>
</row>
</tbody>
</tgroup>
<caption><para>Captions are allowed!</para></caption>
</table>
</listitem>
<listitem>
<para>if more than one column contains row headers, set the
<code>rowheader</code> attribute on the relevant
<code>colspec</code> declarations to <code>headers</code>.</para>
<table frame="all">
<title>example: a table with two columns of row headers</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1.0*" rowheader="headers"/>
<colspec colname="c2" colwidth="1.0*" rowheader="headers"/>
<colspec colname="c3" colwidth="1.0*"/>
<tbody>
<row>
<entry morerows="2">points</entry>
<entry>Mark</entry>
<entry>11,123.45</entry>
</row>
<row>
<entry>Peter</entry>
<entry>11,012.34</entry>
</row>
<row>
<entry>Cindy</entry>
<entry>10,987.64</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</itemizedlist>
<para>Note: the examples here are mere constructions to demonstrate docBook
functionaliy options. In the wild, the first variant would be preferred to the
second from an accessibility standpoint, following the good old
<acronym>KISS<alt>Keep It Simple
Stupid!</alt></acronym>-principle.</para>
</section>
</section>
<section>
<title>Explicity associate table data with its headers</title>
<para>This step is necessary for more complex tables, for example containing row AND
column headers, multiple column header rows, or spanned entries.</para>
<para>Analagously to the HTML model, DocBook CALS tables offer two mechanisms to achieve
this:</para>
<itemizedlist>
<listitem>
<para><code>scope</code></para>
<para>The scope attribute is used on table entries functioning as headers to
explicitly define the range of entries they apply to (a row, a column, a
row group, or a column group).</para>
<table frame="all" rowheader="firstcol">
<title>example: assuring complex table accessibility using
<code>scope</code>
</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1.0*"/>
<colspec colname="c2" colwidth="1.0*"/>
<colspec colname="c3" colwidth="1.0*"/>
<thead>
<row>
<entry morerows="1"></entry>
<entry namest="c2" nameend="c3" scope="colgroup">points</entry>
</row>
<row>
<entry scope="col">expected</entry>
<entry scope="col">actual</entry>
</row>
</thead>
<tbody>
<row>
<entry scope="row">Mark</entry>
<entry>10,000</entry>
<entry>11,123.45</entry>
</row>
<row>
<entry scope="row">Peter</entry>
<entry>9,000</entry>
<entry>11,012.34</entry>
</row>
<row>
<entry scope="row">Cindy</entry>
<entry>10,000</entry>
<entry>10,987.64</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
<listitem>
<para><code>xml:id</code> and <code>headers</code></para>
<para>With this dynamic duo, very granular association of table data to its
headers can be accomplished. The header entries are identified via <code>xml:id</code>
attributes, which are then referenced in the <code>headers</code> attribute on data entries.
</para>
<table frame="all" rowheader="firstcol">
<title>example: assuring complex table accessibility using
<code>headers</code>
</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="1.0*"/>
<colspec colname="c2" colwidth="1.0*"/>
<colspec colname="c3" colwidth="1.0*"/>
<thead>
<row>
<entry morerows="1"></entry>
<entry namest="c2" nameend="c3" xml:id="pts">points</entry>
</row>
<row>
<entry xml:id="exp" headers="pts">expected</entry>
<entry xml:id="act" headers="pts">actual</entry>
</row>
</thead>
<tbody>
<row>
<entry xml:id="name1">Mark</entry>
<entry headers="name1 exp pts">10,000</entry>
<entry headers="name1 act pts">11,123.45</entry>
</row>
<row>
<entry xml:id="name2">Peter</entry>
<entry headers="name2 exp pts">9,000</entry>
<entry headers="name2 act pts">11,012.34</entry>
</row>
<row>
<entry xml:id="name3">Cindy</entry>
<entry headers="name3 exp pts">10,000</entry>
<entry headers="name3 act pts">10,987.64</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</itemizedlist>
</section>
</section>
<section>
<title>Documentation</title>
<para>To make the documentation clear concerning the different attribute values for
rowheader depending on context, I would suggest the following wording:</para>
<section><title>docBook Schema</title>
<literallayout>
db.rowheader.attribute =
## Indicates whether or not the entries in columns should be considered row headers
attribute rowheader {
## Indicates that entries in the first column of the table are functionally row headers (analogous to the way that a thead provides column headers).
"firstcol"
|
## Indicates that entries of a column described via colspec are functionally row headers (for cases with more than one column of row headers).
"headers"
|
## Indicates that entries in columns have no special significance with respect to column headers.
"norowheader"
}
</literallayout>
</section>
<section>
<title>The Definitive Guide</title>
<para>Being as it is the definitive guide, it may be useful to include a usage guide along the lines of the one above. However, I could not find "the perfect spot" for this.</para>
<section>
<title>db.cals.table
(<link>http://www.docbook.org/tdg51/en/html/cals.table.html</link>), and db.cals.informaltable (<link>http://www.docbook.org/tdg51/en/html/cals.informaltable.html</link>)</title>
<glosslist>
<glossentry>
<glossterm>rowheader</glossterm>
<glossdef>
<para>Indicates whether or not the entries in the first column should be
considered row headers</para>
<informaltable rowheader="firstcol">
<tgroup cols="2">
<thead>
<row>
<entry scope="col">Enumerated values</entry>
<entry scope="col">Explanation</entry>
</row>
</thead>
<tbody>
<row>
<entry scope="row">â??firstcolâ??</entry>
<entry>Indicates that entries in the first column of the table are
functionally row headers (analogous to the way that a thead
provides column headers).</entry>
</row>
<row>
<entry scope="row">â??headersâ??</entry>
<entry>Do not use in the <code>table</code> context. (For
use in the context of <code>colspec</code>
only.)</entry>
</row>
<row>
<entry scope="row">â??norowheaderâ??</entry>
<entry>Indicates that entries in the first column have no special
significance with respect to column headers.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</glossdef>
</glossentry>
</glosslist>
</section>
<section>
<title>colspec
(<link>http://www.docbook.org/tdg51/en/html/colspec.html</link>)</title>
<glosslist>
<glossentry>
<glossterm>rowheader</glossterm>
<glossdef>
<para>Indicates whether or not the entries in the specified column should be
considered row headers</para>
<informaltable rowheader="firstcol">
<tgroup cols="2">
<thead>
<row>
<entry scope="col">Enumerated values</entry>
<entry scope="col">Explanation</entry>
</row>
</thead>
<tbody>
<row>
<entry scope="row">â??firstcolâ??</entry>
<entry>Do not use in the <code>colspec</code> context. (For use
in the context of <code>table</code> only.)</entry>
</row>
<row>
<entry scope="row">â??headersâ??</entry>
<entry>Indicates that entries in the specified column are
functionally row headers (analogous to the way that a thead
provides column headers).</entry>
</row>
<row>
<entry scope="row">â??norowheaderâ??</entry>
<entry>Indicates that entries in the column have no special
significance with respect to column headers.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</glossdef>
</glossentry>
</glosslist>
</section></section>
</section>
<section>
<title>XSL Transformations</title>
<para>The following transformations are to be added:</para>
<itemizedlist>
<listitem>
<para>HTML</para>
<itemizedlist>
<listitem>
<para>if the colspec for an entry's column specifies rowheaders,
<code>entry</code> --> <code>th</code></para>
</listitem>
<listitem>
<para>assure that empty entries in row-or column-header groups are
transformed to empty <code>td</code>'s</para>
</listitem>
<listitem>
<para>transfer the <code>scope</code> and <code>headers</code> attribute
into the HTML as is.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>ePub?</para>
<para>How must tables be marked up in ePub to be screen reader accessible?</para>
</listitem>
<listitem>
<para>FO?</para>
<para>How must tables be marked up in PDF to be screen reader accessible?</para>
</listitem>
</itemizedlist>
</section>
</article>
Thanks and best regards, --Scott Scott Hudson | PELCO by Schneider Electric | United States | Standards Lead Phone: +1 970 282 1952 | Fax: +1 970 282 1950 | Email: scott.hudson@schneider-electric.com | Site: pdn.pelco.com |
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]