programlisting

programlisting — A literal listing of all or part of a program

Synopsis

Attributes

Common attributes and common linking attributes.

Additional attributes:

  • All of:
    • continuation (enumeration)
      • “continues”
      • “restarts”
    • linenumbering (enumeration)
      • “numbered”
      • “unnumbered”
    • startinglinenumber (integer)
    • language
    • xml:space (enumeration)
      • “preserve”
  • width

Description

A ProgramListing is a verbatim environment for program source or source fragment listings. ProgramListings are often placed in Examples or Figures so that they can be cross-referenced from the text.

Processing Expectations

Formatted as a displayed block. This element is displayed “verbatim”; whitespace and linebreaks within this element are significant. ProgramListings are usually displayed in a fixed width font.

Other markup within a ProgramListing is recognized. Contrast this with systems like LaTeX, in which verbatim environments disable markup recognition. If you want to disable markup recognition, you must use a CDATA section:


<programlisting>
<![CDATA[
This is a programlisting so white       space and line
breaks are significant.  But it is also a CDATA
section so <emphasis>tags</emphasis> and &entities;
are not recognized.  The only markup that is recognized
is the end-of-section marker, which is two
"]"'s in a row followed by a >.

]]>

</programlisting>

Two markup tags have special significance in ProgramListings: CO and LineAnnotation. A CO identifies the location of a Callout. A LineAnnotation is a comment, added by the documentor—not the programmer.

Processing expectations

This element is displayed “verbatim”; whitespace and linebreaks within this element are significant.

Attributes

Common attributes and common linking attributes.

continuation

Determines whether line numbering continues from the previous element or restarts.

Enumerated values:

continues

Line numbering continues from the immediately preceding element with the same name.

restarts

Line numbering restarts (begins at 1, usually).

language

Identifies the language (i.e. programming language) of the verbatim content.

linenumbering

Determines whether lines are numbered.

Enumerated values:

numbered

Lines are numbered.

unnumbered

Lines are not numbered.

startinglinenumber

Specifies the initial line number.

width

FIXME:

xml:space

Can be used to indicate explicitly that whitespace in the verbatim environment is preserved. Whitespace must always be preserved in verbatim environments whether this attribute is specified or not.

Enumerated values:

preserve

Whitespace must be preserved.

See Also

computeroutput, lineannotation, literallayout, screen, screenshot, synopsis, userinput

ChangeLog

This alpha reference page is $Revision: 1.3 $ published $Date: 2005/07/07 16:41:13 $.