db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Kim Haase (JIRA)" <j...@apache.org>
Subject [jira] [Commented] (DERBY-5171) Fix uses of <alt> and <desc> elements and figure captions
Date Thu, 31 Mar 2011 20:53:05 GMT

    [ https://issues.apache.org/jira/browse/DERBY-5171?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13014197#comment-13014197

Kim Haase commented on DERBY-5171:

The <desc> element, which can come after the title (caption) of a table or figure, should
provide a fairly detailed description that could go in the summary attribute of a table or,
for a figure, perhaps a linked-to file with a description readable by a screen reader for
the visually impaired. Although the DITA spec doesn't say so, a good use of the <desc>
content would be to provide additional content for the visually impaired, while the introductory
description of the figure or table should be sufficient for sighted readers.

In practice, the DITA toolkit just places the text of the <desc> element after the table
or figure caption, visible to all. In the frames version of the manuals, there is no line
break; in the one-page HTML and PDF, there are line breaks surrounding the description. I
think that if the text in the <desc> element is useful to all readers, it should be
placed in the introductory text instead of the <desc> element.

The <alt> element is meant to translate into an alt attribute in the HTML img tag, a
brief placeholder for an image that appears only if the image is missing for some reason.
This should be a short phrase, but often in the Derby docs it is a very long description more
appropriate to a <desc> element. Moreover, although the alt text is included in the
frames version of the documentation, it does not appear in the one-page HTML or the PDF.

There is no good solution to this problem at present, because of problems with the toolkit.
At this point it probably makes sense to leave all figure text that should be available only
to the visually impaired in <alt> elements, rather than make them visible to everyone.
For the few tables that have <desc> elements, the text really belongs in introductory
text (these are at the end of the Reference Manual).

See http://db.apache.org/derby/docs/dev/devguide/cdevdvlp27610.html and http://db.apache.org/derby/docs/dev/tuning/ctundepth32379.html
for examples of what needs fixing.

> Fix uses of <alt> and <desc> elements and figure captions
> ---------------------------------------------------------
>                 Key: DERBY-5171
>                 URL: https://issues.apache.org/jira/browse/DERBY-5171
>             Project: Derby
>          Issue Type: Sub-task
>          Components: Documentation
>    Affects Versions:
>            Reporter: Kim Haase
>            Assignee: Kim Haase
>            Priority: Minor
> The DITA elements <alt> and <desc> often don't work well in the Derby documentation;
the toolkit doesn't handle them well, and they are not used consistently in the source. Also,
figure captions are inconsistent; they should be short descriptive noun phrases, but often
they are complete sentences or very wordy phrases that really belong in introductory text.
> More details will follow in a comment.

This message is automatically generated by JIRA.
For more information on JIRA, see: http://www.atlassian.com/software/jira

View raw message