JDK-4636655 : stddoclet: Add title attribute to <FRAME> tags 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-12
  • Updated: 2014-05-05
  • Resolved: 2002-09-02
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 Availabitlity Release.

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

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