United StatesChange Country, Oracle Worldwide Web Sites Communities I am a... I want to...
JDK-4637604 : stddoclet: Add "summary" attribute to tables for accessibility

Submit Date:
Updated Date:
Project Name:
Resolved Date:
Affected Versions:
Fixed Versions:
1.4.2 (mantis)

Related Reports

Sub Tasks

Name: dk30142			Date: 02/13/2002

In the <TABLE> tags for summary tables, add "summary" attribute, 
such as:

<TABLE border="0" 
       summary="This table lists the direct methods of this class,
                with modifiers, return type, name and description.">

Perhaps the word "this" can be replace by the name of the class.
And the word "methods" can be modified to say "public and package-private
methods" according to the options passed in when the docs were generated.

The navigation tables (two tables, nested) would need a different
kind of summary.  

Various guidelines follow:

Sun Accessibility Program Office ----------------------------
This is an update to the general table description guidelines the 
proposed a while back.

                Describing Tables, 508

When Tables may also need a "summary" (similar to a "longdesc")
1. If the table isn't adequately introduced in preceding text and
   the "caption" alone doesn't adequately describe the table.
2. If it has a non-standard structure (e.g. tables within tables).

General Guideline for a Table "summary".
1. Provide the information you feel is missing in the table's "caption"
   and the text surrounding the table. Be as detailed as desired,
   there are no text length limitations associated with the "summary"
2. Do not add how many rows and columns the Table has, AT can readily
   obtain and present this information from the information currently
   generated in the Tables Sun generates.

W3C Guidelines ------------------------------------------

Provide a summary via the "summary" attribute. Summaries are
especially useful for non-visual readers. A summary of the
relationships among cells is especially important for tables with
nested headings, cells that span multiple columns or rows, or other
relationships that may not be obvious from analyzing the structure of
the table but that may be apparent in a visual rendering of the
table. A summary may also describe how the table fits into the context
of the current document. If no caption is provided, it is even more
critical to provide a summary. Two examples:

   1."This table charts the number of cups of coffee consumed by 
      each senator, the type of coffee (decaf or regular), and
      whether taken with sugar." 
   2."Total required by pollution control standards as of 
      January 1, 1971. Commercial category includes stores, insurance
      companies and banks. The table is divided into two columns. 
      The left-hand column is 'Total investment required in billions
      of dollars'. The right--hand column is 'Spending' and is divided 
      into three sub-columns. The first sub-column is titled
      '1970 actual in millions of dollars', the second is '1971 
      planned in millions of dollars', and the third is 'Percent 
      change, 1970 versus 1971.' The rows are industries." [NBA, 1996]. 

508 Guidelines for Sun Computer System Products ---------------
From Pat Gee-Best

<TABLE DIR="LTR" SUMMARY="Table provides a description of the CPU
       Configuration information.">

       Notice the DIR attribute -- this tells the audio reader the direction
       the table should be read, which is left-to-right (LTR).

       This is inserted by AltText-Short



BugTraq+ Release Management Values





Name: dk30142			Date: 02/13/2002


Needed for accessibility
###@###.### 2002-02-13

Navigation/Version Nested Tables: (top and bottom of each page)
    No summary attribute needed for these tables, for
    reasons mentioned here:

Earl said if a navigation table has a hypertext link ahead of it
for jumping over the table, with alt text, then the table itself does 
not need, and would preferably not have a summary attribute.
Therefore, the navigation tables have no summary.

Summary Tables:
- Nested Class Summary
- Field Summary              
- Constructor Summary
- Method Summary             
    No summary attribute needed for these tables, for 
    reasons mentioned here:

The summary tables (listed below) all have a first row
heading that acts as a caption.  For example, the table
with heading "Method Summary" would not need a summary
attribute stating "Table with summary of methods", as that 
would be redundant.  One thing possibly important to
add would be "the first column contains modifiers and return
types, the second columns contains names, parameter lists
and a description".  However, page speakers (such as JAWS)
by default don't identify which column you're in -- it
just reads across naturally from left to right columns.
Therefore, it would not help to mention what is contained
in each column.  When the table treated as "for format only",
the page speaker results are as desired.  Another possible 
thing to mention is the name of the class and the scope of
possible access modifier, such as:
"Public and protected methods for String class".
However, the access applies not just to this table, but 
to the entire document, so does not need to be repeated
(unless jumping frequently between documents with different
access, which is unlikely).  Also, a the word "private"
is spoken when encountering a private member.
There would be value in repeating the class, as sight-impaired
people cannot quickly scan to the top of the page, the
only place where the class is reliably mentioned.
However, the same could be said for chapter titles in
books, and I have seen no such recommendation in the
508 literature for this.
Conclusion:  No summary attribute is needed for summary

- Nested classes inherited from class X
- Fields inherited from class X
- Methods inherited from class X
    No summary needed for these tables, as these headings
    are entirely satisfactory, and the tables are simple,
    two-cell tables for format only

- Field Detail
- Constructor Detail
- Method Detail
    No summary needed for these, as they are single-cell tables
    for format only

Likewise for the table of classes on the package-summary.html
page and table of packages on the overview-summary.html pages.
These are both simple tables for formatting only that read
naturally from left to right.

Considered for summary tables and rejected:

  summary="This table lists the direct methods of this class,
           with modifiers, return type, name and description."

  summary="This table lists the direct methods of this class
           with declarations and descriptions."

  summary="Method table with declarations and descriptions."

  summary="Public and protected methods for String class".

Closing out this RFE as "will not fix".

###@###.### 2002-07-12

Earl is recommending we mark tables with:


to indicate they are for layout only.  (We are inquiring with Accessibility
Program Office if summary="" might be better.)

###@###.### 2002-09-12

Alan Sommerer has settled on summary="layout" for the rest
of the department.  Because javadoc has so many tables 
per page, it would be better for it to be silent. 
JAWS 4.0 had a bug where it spoke summary="" as 
"summary colon left paren null right paren" 
however, in 4.5 this is fixed to be silent.
Home Page Reader is also silent for this (when you
press Alt-F1).  Therefore, we are settling on:


###@###.### 2002-10-31

Added the empty string to the summary:


JAWS 4.5 and HPR both are silent when encountering this.
This convention may be adopted by the W3C.

The regression test is in <ws>/test/com/sun/javadoc/AccessSummary.html

###@###.### 2002-10-31

Hardware and Software, Engineered to Work Together