Derby
  1. Derby
  2. DERBY-5135

Derby documentation needs accessibility improvements

    Details

    • Type: Task Task
    • Status: Closed
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: 10.7.1.1
    • Fix Version/s: 10.8.2.2, 10.9.1.0
    • Component/s: Documentation
    • Labels:
      None

      Description

      Accessibility is increasingly important for documentation. The Derby HTML documentation currently fails accessibility requirements, although the frames versions of the manuals seem closer to accessibility than the single-file HTML versions.

      I will file a sub-task for some fairly easy fixes to the documentation and will describe some of the harder problems in a comment later.

        Issue Links

          Activity

          Hide
          Kim Haase added a comment -

          Tables in the Derby documentation have some accessibility problems that don't seem easy to fix.

          Accessible tables require a summary attribute. Currently the tables in the frames HTML docs have empty summary attributes:

          summary=""

          DITA, even in its more recent versions, does not have an attribute to specify a table summary. Providing a meaningful summary for each table would require some complicated processing, maybe of a comment in the topic source.

          Also, accessibility requires that table headers and table cells be linked by an id value. Table headers specify an id for each column:

          <th valign="top" width="50%" id="N100A8">Before Transformation</th>
          <th valign="top" width="50%" id="N100AF">After Transformation</th>

          Table cells then reference this id in their headers attribute – except that in formal tables, our DITA toolkit puts an extra space in the id that makes it invalid:

          <td valign="top" width="50%" headers="N100A8 "><strong><samp class="codeph">c1 < ANY (SELECT ...)</samp></strong></td>
          <td valign="top" width="50%" headers="N100AF "><strong><samp class="codeph">c1 < (SELECT ...)</samp></strong></td>

          The simpletable and choicetable elements are generated correctly, but formal tables aren't. I have not been able to figure out what's wrong with the formal table generation.

          Show
          Kim Haase added a comment - Tables in the Derby documentation have some accessibility problems that don't seem easy to fix. Accessible tables require a summary attribute. Currently the tables in the frames HTML docs have empty summary attributes: summary="" DITA, even in its more recent versions, does not have an attribute to specify a table summary. Providing a meaningful summary for each table would require some complicated processing, maybe of a comment in the topic source. Also, accessibility requires that table headers and table cells be linked by an id value. Table headers specify an id for each column: <th valign="top" width="50%" id="N100A8">Before Transformation</th> <th valign="top" width="50%" id="N100AF">After Transformation</th> Table cells then reference this id in their headers attribute – except that in formal tables, our DITA toolkit puts an extra space in the id that makes it invalid: <td valign="top" width="50%" headers="N100A8 "><strong><samp class="codeph">c1 < ANY (SELECT ...)</samp></strong></td> <td valign="top" width="50%" headers="N100AF "><strong><samp class="codeph">c1 < (SELECT ...)</samp></strong></td> The simpletable and choicetable elements are generated correctly, but formal tables aren't. I have not been able to figure out what's wrong with the formal table generation.
          Hide
          Kim Haase added a comment -

          API documentation accessibility is another issue. Reportedly the JDK 7 version of the javadoc tool will generate accessible documentation; previous versions do not. I don't know whether, or when, the Derby build process could switch to the JDK 7 version of the javadoc tool for generating the shipped versions of the JDBC API docs.

          Show
          Kim Haase added a comment - API documentation accessibility is another issue. Reportedly the JDK 7 version of the javadoc tool will generate accessible documentation; previous versions do not. I don't know whether, or when, the Derby build process could switch to the JDK 7 version of the javadoc tool for generating the shipped versions of the JDBC API docs.
          Hide
          Kim Haase added a comment - - edited

          Accessibility standards can be found at the following locations:

          W3C Web Content Accessibility Guidelines: http://www.w3.org/TR/WCAG10/
          Section 508 standards (USA only): http://www.access-board.gov/sec508/guide/

          Show
          Kim Haase added a comment - - edited Accessibility standards can be found at the following locations: W3C Web Content Accessibility Guidelines: http://www.w3.org/TR/WCAG10/ Section 508 standards (USA only): http://www.access-board.gov/sec508/guide/
          Hide
          Kim Haase added a comment -

          I am resolving this task, since the frames version of the docs meets accessibility requirements sufficiently. A new task can be created if more work is needed.

          Show
          Kim Haase added a comment - I am resolving this task, since the frames version of the docs meets accessibility requirements sufficiently. A new task can be created if more work is needed.
          Hide
          Kim Haase added a comment -

          Reopening to add new accessibility task.

          Show
          Kim Haase added a comment - Reopening to add new accessibility task.
          Hide
          Kim Haase added a comment -

          All tasks have now been completed.

          Show
          Kim Haase added a comment - All tasks have now been completed.
          Hide
          Kim Haase added a comment -

          Closing, since all sub-tasks have been closed and no more seem to be needed.

          Show
          Kim Haase added a comment - Closing, since all sub-tasks have been closed and no more seem to be needed.

            People

            • Assignee:
              Kim Haase
              Reporter:
              Kim Haase
            • Votes:
              0 Vote for this issue
              Watchers:
              1 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:

                Development