You are viewing a plain text version of this content. The canonical link for it is here.
Posted to derby-dev@db.apache.org by "Kim Haase (JIRA)" <ji...@apache.org> on 2011/03/31 22:23:06 UTC
[jira] [Created] (DERBY-5171) Fix uses of and elements
and figure captions
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
[jira] [Resolved] (DERBY-5171) Fix uses of and
elements and figure captions
Posted by "Kim Haase (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-5171?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Kim Haase resolved DERBY-5171.
------------------------------
Resolution: Fixed
Fix Version/s: 10.8.1.1
Issue & fix info: (was: [Patch Available])
Committed patch DERBY-5171.diff to documentation trunk at revision 1090436.
Merged to 10.8 doc branch at revision 1090455.
> 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
> Fix For: 10.8.1.1
>
> Attachments: DERBY-5171.diff, DERBY-5171.stat, DERBY-5171.zip
>
>
> 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
[jira] [Updated] (DERBY-5171) Fix uses of and elements
and figure captions
Posted by "Kim Haase (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-5171?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Kim Haase updated DERBY-5171:
-----------------------------
Attachment: DERBY-5171.zip
DERBY-5171.stat
DERBY-5171.diff
Attaching DERBY-5171.diff, DERBY-5171.stat, and DERBY-5171.zip, with changes to the following files:
M src/tuning/ctundepth32379.dita
M src/devguide/cdevdeploy855655.dita
M src/devguide/cdevdeploy855368.dita
M src/devguide/cdevconcepts16400.dita
M src/devguide/cdevcsecure42374.dita
M src/devguide/cdevdvlp40724.dita
M src/devguide/cdevdvlp27610.dita
M src/devguide/cdevconcepts28436.dita
M src/devguide/cdevcsecuree.dita
The patch provides an introduction for each figure that lacked one, and gives each figure a noun-phrase title if needed.
It also puts alt text all on one line to prevent " " characters from being inserted into the HTML output at every line break in the source.
Additional fixes:
src/tuning/ctundepth32379.dita
No need to say "new in JDBC 3.0" any more
Fixed some paragraphing
src/devguide/cdevcsecuree.dita
Fixed cases in title and elsewhere
Fixed Java terminology
Comments are welcome. If I don't hear anything, I'll plan to commit the patch at the end of the week. There is no rush, since this doesn't need to get into 10.8.
> 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
> Attachments: DERBY-5171.diff, DERBY-5171.stat, DERBY-5171.zip
>
>
> 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
[jira] [Updated] (DERBY-5171) Fix uses of and elements
and figure captions
Posted by "Kim Haase (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-5171?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Kim Haase updated DERBY-5171:
-----------------------------
Issue & fix info: [Patch Available]
> 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
> Attachments: DERBY-5171.diff, DERBY-5171.stat, DERBY-5171.zip
>
>
> 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
[jira] [Commented] (DERBY-5171) Fix uses of and
elements and figure captions
Posted by "Kim Haase (JIRA)" <ji...@apache.org>.
[ 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
[jira] [Closed] (DERBY-5171) Fix uses of and elements
and figure captions
Posted by "Kim Haase (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-5171?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Kim Haase closed DERBY-5171.
----------------------------
Changes have appeared in 10.8 and latest alpha docs.
> 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
> Fix For: 10.8.1.2
>
> Attachments: DERBY-5171.diff, DERBY-5171.stat, DERBY-5171.zip
>
>
> 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