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 <programlisting>...</programlisting>.

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 element <screen>...</screen> 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 opening <screen> or <programlisting> tag; so, if you start your code display on the line following that tag, the display will start with a blank line.

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 <screen> or <programlisting> 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, for each callout that you used in the display, add one element of the form <callout arearefs="I"> for each callout you used above. 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>

9.2. Poetry

When formatting poetry and similar text, use the <literallayout> tag. Like the <programlisting> element, it presents the content with all whitespace and line breaks intact, but it uses a regular text font. Here's an example from Piet Hein:

Problems worthy
Of attack
Prove their worth
By hitting back.

Writing documentation with DocBook-XML 4.2