United StatesChange Country, Oracle Worldwide Web Sites Communities I am a... I want to...
Bug ID: JDK-4636655 stddoclet: Add title attribute to <FRAME> tags for accessibility
JDK-4636655 : stddoclet: Add title attribute to tags for accessibility

Details
Type:
Enhancement
Submit Date:
2002-02-12
Status:
Resolved
Updated Date:
2003-04-12
Project Name:
JDK
Resolved Date:
2002-09-02
Component:
docs
OS:
generic
Sub-Component:
doclet
CPU:
generic
Priority:
P4
Resolution:
Fixed
Affected Versions:
1.4.0
Fixed Versions:
1.4.2 (mantis)

Related Reports

Sub Tasks

Description
Make sure all <FRAME> tags contain a title attribute.  For example,
index.html currently contains <FRAME) tags but not title attribute:

<FRAMESET cols="20%,80%">
<FRAMESET rows="30%,70%">
<FRAME src="overview-frame.html" name="packageListFrame">
<FRAME src="allclasses-frame.html" name="packageFrame">
</FRAMESET>
<FRAME src="overview-summary.html" name="classFrame">
</FRAMESET>

Here is an example of how the title attributes might be added:

<FRAME src="overview-frame.html" name="packageListFrame" title="All packages">
<FRAME src="allclasses-frame.html" name="packageFrame" title="All classes and interfaces">
<FRAME src="com/sun/javadoc/package-summary.html" name="classFrame" title="Package, class and interface descriptions">

Analysis:
The heading "All Classes" is presented visually to the reader.
The title "All classes and interfaces" above provides more.  
However, non-static nested classes are not included, so a precisely
accurate description would be:

 "All top-level and static nested classes and interfaces".  

However, this seems unwieldy to grok in a single pass.  Another approach 
would be:

  "All classes and interfaces (except non-static nested)."

Also, the title could mention that interfaces are emphasized.
Rather than doing that here, another bug 4714257 describes
how to do that for each individual hypertext link.

For other examples, see:

  http://bobby.cast.org:80/bobby/html/en/gls/g39.html

This is an accessibility requirement as spelled out by
evaluating a 1.4.0 javadoc-generated document.  The requirement
is specified at:

  http://www.cast.org/bobby/

and W3C Accessibility Guidelines:

  http://www.w3.org/TR/1999/WAI-WEBCONTENT-19990505/#gl-complex-elements

  12.1 Title each frame to facilitate frame identification and navigation. [Priority 1]
       For example, in HTML use the "title" attribute on FRAME elements. 
       HTML Techniques: Providing a frame title 

          <FRAMESET cols="10%, 90%"
                    title="Our library of electronic documents">  
              <FRAME src="nav.html" title="Navigation bar">  
              <FRAME src="doc.html" title="Documents">
              <NOFRAMES>
                 <A href="lib.html" title="Library link">   
                       Select to go to the electronic library</A>  
              </NOFRAMES>
          </FRAMESET>

and U.S. Access Board

  http://www.access-board.gov/sec508/guide/1194.22.htm#(i)

  "What is the best method for identifying frames?
  The most obvious way to accomplish this requirement is to include text within 
  the body of each frame that clearly identifies the frame. For instance, 
  in the case of the navigation bar, a web developer should consider putting 
  words such as "Navigational Links" at the beginning of the contents of the 
  frame to let all users know that the frame depicts navigational links. 
  Providing titles like this at the top of the contents of each frame will 
  satisfy these requirements. An additional measure that should be considered 
  by agencies is to include meaningful text in the <frame> tag's "title"
  attribute."

Analysis:
The current javadoc frames already have text headings:
 - Upper left frame heading: "Packages"
 - Lower left frame heading: "All Classes"
Therefore, title attributes are not required for these two frames.
However, the main right frame has no such title and requires a title attribute.
To be consistent, we will add title attributes for all frames.

I tested it by entering into the field in the above Bobby page this documentation 
from the J2SE 1.4 API:

  http://webwork.sfbay/j2se/1.4/docs/api/index.html

Note that a longdesc attribute is not needed in these <FRAME> tags, as the titles 
are explanatory enough:

   12.2 Describe the purpose of frames and how frames relate to each other if it is 
        not obvious by frame titles alone. [Priority 2] 

The accessibility contact is ###@###.###

Possible wording for lower-left frame:

(1) All classes and interfaces (except non-static nested types) 
(2) All classes and interfaces (except inner types)
(3) Top-level and static nested classes and interfaces

  (2) rests on people knowing the distinction between 
  inner and nested types.  The term "inner" is not otherwise
  used in the javadoc HTML output.

###@###.### 2002-07-28

                                    

Comments
EVALUATION

Easy and important for accessibility.
###@###.### 2002-02-12

Webrev is at:
http://frog.sfbay.sun.com/net/jano.sfbay/export/disk01/tools/doclets/stddoclet/webrevs/4636655-accessframetitle/webrev/

Regression test is at:
<ws>/test/com/sun/javadoc/AccessFrameTitle/AccessFrameTitle.java
                                     
2004-06-11
CONVERTED DATA

BugTraq+ Release Management Values

COMMIT TO FIX:
mantis
mantis-b02

FIXED IN:
mantis
mantis-b02

INTEGRATED IN:
mantis
mantis-b02


                                     
2004-06-14



Hardware and Software, Engineered to Work Together