Details

    • Type: Sub-task Sub-task
    • Status: Closed
    • Priority: Minor Minor
    • Resolution: Fixed
    • Affects Version/s: 10.7.1.1
    • Fix Version/s: 10.8.1.2
    • Component/s: Documentation
    • Labels:
      None

      Description

      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.

      1. DERBY-5171.zip
        26 kB
        Kim Haase
      2. DERBY-5171.stat
        0.4 kB
        Kim Haase
      3. DERBY-5171.diff
        24 kB
        Kim Haase

        Activity

        Hide
        Kim Haase added a comment -

        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.

        Show
        Kim Haase added a comment - 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.
        Hide
        Kim Haase added a comment -

        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.

        Show
        Kim Haase added a comment - 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.
        Hide
        Kim Haase added a comment -

        Committed patch DERBY-5171.diff to documentation trunk at revision 1090436.
        Merged to 10.8 doc branch at revision 1090455.

        Show
        Kim Haase added a comment - Committed patch DERBY-5171 .diff to documentation trunk at revision 1090436. Merged to 10.8 doc branch at revision 1090455.
        Hide
        Kim Haase added a comment -

        Changes have appeared in 10.8 and latest alpha docs.

        Show
        Kim Haase added a comment - Changes have appeared in 10.8 and latest alpha docs.

          People

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

            Dates

            • Created:
              Updated:
              Resolved:

              Development