programlisting — A literal listing of all or part of a program
programlisting ::=
(info
? db.titleforbidden.info, ((text |
lineannotation
| Bibliography inlines | Computer-output inlines | Error inlines | Graphic inlines | GUI inlines | Indexing inlines | Keyboard inlines | Linking inlines | Markup inlines | Math inlines | Object-oriented programming inlines
| Operating system inlines |
Product inlines | Programming inlines | Publishing inlines | Technical inlines | Ubiquitous inlines | User-input inlines)* |
textobject
))
Common attributes and common linking attributes.
Additional attributes:
continuation
(enumeration) = “continues” | “restarts”
linenumbering
(enumeration) = “numbered” | “unnumbered”
startinglinenumber
(integer)
language
xml:space
(enumeration) = “preserve”
width
(nonNegativeInteger)
A programlisting
is a verbatim environment for
program source or source fragment listings. The
programlisting
s are often placed in
example
s or figure
s so that they
can be cross-referenced from the text.
Formatted as a displayed block. This element is displayed
“verbatim”; whitespace and line breaks within this element are
significant. The programlisting
s 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
programlisting
s: co
and
lineannotation
. A co
identifies
the location of a callout
. A
lineannotation
is a comment, added by the
documentor—not the programmer.
Common attributes and common linking attributes.
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). |
Identifies the language (i.e., programming language) of the verbatim content.
Determines whether lines are numbered.
Enumerated values: | |
---|---|
“numbered” | Lines are numbered. |
“unnumbered” | Lines are not numbered. |
Specifies the initial line number.
Specifies the width (in characters) of the element.
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. |