9. Verbatim displays

By displays, we mean the presentation of information in some form other than a paragraph: illustrations, representations of computer screens, and so on.

To present one or more lines in a monospaced (fixed-width) font, as in a computer program, enclose the lines within a programlisting element.

For example, this input:

<programlisting>
    10 PRINT "BASIC IS OVER 40 YEARS OLD"
    20 GOTO 10
    30 END
</programlisting>

produces this output:

    10 PRINT "BASIC IS OVER 40 YEARS OLD"
    20 GOTO 10
    30 END

You can also use the screen element to display something that appears on a screen. The formatting is the same as for the programlisting element.

Line breaks are preserved starting immediately after the start tag. Therefore, if you start your code display on the line following that tag, the display will start with a blank line. There is a way to avoid this: move the closing “>” of the start tag to the beginning of the first line of code. Here is the above example formatted so as to eliminate the initial blank line:

<programlisting
>    10 PRINT "BASIC IS OVER 40 YEARS OLD"
    20 GOTO 10
    30 END
</programlisting>

9.1. Callouts in verbatim displays

Sometimes you want to present a program listing or screen shot with callouts, little numbered graphic tags that appear within the display. Then, following the display, you present textual discussions for each callout. Here's an example:

    AWAKE! for Morning in the Bowl of Night 
    Has flung the Stone that puts the Stars to Flight:
    And Lo! the Hunter of the East has caught
    The Sultan's Turret in a Noose of Light.

	Note the gratuitous capitalization.
	It appears that someone has struck the Sultan on the turret with an alarm clock.

In order to use callouts, you must have a subdirectory named callouts in the same directory as your document, containing the actual callout images in two formats (PNG for web pages, PDF for print presentation). There are two ways to make these callouts available under Linux.

Make a soft link from your directory:

ln -s /u/www/docs/tcc/help/image/callouts .

Or, copy an archive file containing that whole directory and unpack it in your directory:
```
cp /u/www/docs/tcc/help/image/callouts.tgz .
tar -xvzf callouts.tgz
```

That directory currently contains graphics for twenty callouts numbered 1 to 20. If you don't like their appearance or need more than 20, see the README in that directory to see how to create your own.

Once you have installed the callout graphic files, to use callouts in your programlisting or screen element:

Add an element of the form <co id="I"/> within the display where you want a callout to appear. Invent a unique identifier I to be used later.
When you have decorated your display with co elements, add a calloutlist element after the end of the display.
Within that calloutlist element, place one callout element for each co element in the display.
To each callout element, add an attribute of the form arearefs="I", where the value of I is the value of the id attribute of the corresponding co element.
Add your textual description (or graphics or whatever) within the callout element. If you need to put anything other than ordinary text inside the callout element, wrap it inside a para element.

Here's how the above example looks in source form:

  <screen
>    AWAKE! for Morning in the Bowl of Night <co id="khay1"/>
    Has flung the Stone that puts the Stars to Flight:
    And Lo! the Hunter of the East has caught
    The Sultan's Turret in a Noose of Light. <co id="khay2"/>
  </screen>
  <calloutlist>
    <callout arearefs="khay1">
      Note the gratuitous capitalization.
    </callout>
    <callout arearefs="khay2">
      It appears that someone has struck the Sultan on the
      turret with an alarm clock.
    </callout>
  </calloutlist>

Writing documentation with DocBook-XML 4.3

9. Verbatim displays

9.1. Callouts in verbatim displays