JDK-4637604 : stddoclet: Add "summary" attribute to tables for accessibility
  • Type: Enhancement
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 1.4.0
  • Priority: P4
  • Status: Resolved
  • Resolution: Fixed
  • OS: generic
  • CPU: generic
  • Submitted: 2002-02-13
  • Updated: 2014-05-05
  • Resolved: 2002-11-07
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
1.4.2 mantisFixed
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

CONVERTED DATA BugTraq+ Release Management Values COMMIT TO FIX: mantis FIXED IN: mantis INTEGRATED IN: mantis mantis-b07

WORK AROUND Name: dk30142 Date: 02/13/2002 ======================================================================

EVALUATION 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 tables. ----------- - 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: title="" 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: summary="" ###@###.### 2002-10-31

PUBLIC COMMENTS Added the empty string to the summary: <TABLE 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