Long descriptions

DocBook XSL also provides support for the longdesc attribute in HTML IMG tags. This attribute lets you specify a URL that points to a long description of the image. That feature would be particularly helpful for complex graphics being served to vision-impaired readers.

To create a long description, you add another textobject element that does not contain a phrase element. Any textobject that does will be used as the alt text. Here is the previous example with both.

<mediaobject  id="MousePicture">
  <imageobject  role="html">
    <imagedata  format="PNG"  fileref="mouse.png"/>
  </imageobject>
  <imageobject  role="fo">
    <imagedata  format="SVG"  fileref="mouse.svg"/>
  </imageobject>
  <textobject>
    <phrase>Picture of mouse</phrase>
  </textobject>
  <textobject id="foo">
    <formalpara>
      <title>Mouse mechanics</title>
      <para>The mouse consists of a rolling ball and two or three buttons.
      </para>
    </formalpara>
    <para>...</para>
  </textobject>
</mediaobject>

The HTML stylesheet does quite a bit of processing with this second textobject.

  1. It creates a file named ld-xxxx.html where xxxx is some generated id.

  2. It processes the content of the textobject using the stylesheet and writes the output to that file.

  3. It adds an HTML link to the current page using the mark [D] as the text and the filename as the href URL. The link appears below the graphic and right aligned.

When the reader clicks on the [D] link, another window pops up showing the formatted content.

There are limitations on what DocBook markup you can use inside the textobject for a long description. No hierarchical elements like chapter or section are permitted. You can use block elements like paragraphs, lists, admonitions, and literallayout. If you want to start with a title, try using a formalpara. See the reference page for textobject for complete details.