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

          Kim Haase created issue -
          Kim Haase made changes -
          Field Original Value New Value
          Assignee Kim Haase [ chaase3 ]
          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/
          Kim Haase made changes -
          Link This issue incorporates DERBY-4408 [ DERBY-4408 ]
          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.
          Kim Haase made changes -
          Status Open [ 1 ] Resolved [ 5 ]
          Fix Version/s 10.8.2.2 [ 12317968 ]
          Resolution Fixed [ 1 ]
          Kim Haase made changes -
          Status Resolved [ 5 ] Closed [ 6 ]
          Hide
          Kim Haase added a comment -

          Reopening to add new accessibility task.

          Show
          Kim Haase added a comment - Reopening to add new accessibility task.
          Kim Haase made changes -
          Resolution Fixed [ 1 ]
          Status Closed [ 6 ] Reopened [ 4 ]
          Hide
          Kim Haase added a comment -

          All tasks have now been completed.

          Show
          Kim Haase added a comment - All tasks have now been completed.
          Kim Haase made changes -
          Status Reopened [ 4 ] Resolved [ 5 ]
          Fix Version/s 10.9.1.0 [ 12316344 ]
          Resolution Fixed [ 1 ]
          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.
          Kim Haase made changes -
          Status Resolved [ 5 ] Closed [ 6 ]
          Gavin made changes -
          Workflow jira [ 12607774 ] Default workflow, editable Closed status [ 12801864 ]
          Transition Time In Source Status Execution Times Last Executer Last Execution Date
          Open Open Resolved Resolved
          232d 21h 51m 1 Kim Haase 03/Nov/11 18:46
          Closed Closed Reopened Reopened
          122d 21h 12m 1 Kim Haase 05/Mar/12 15:59
          Reopened Reopened Resolved Resolved
          91d 1h 46m 1 Kim Haase 04/Jun/12 17:45
          Resolved Resolved Closed Closed
          127d 1h 41m 2 Kim Haase 09/Oct/12 19:26

            People

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

              Dates

              • Created:
                Updated:
                Resolved:

                Development