[
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: 10.7.1.1
> 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
