$Revision: 1666 $
$Date: 2002-06-12 07:19:37 -0400 (Wed, 12 Jun 2002) $
programlisting — A literal listing of all or part of a program
programlisting ::= (#PCDATA|footnoteref
|xref
|biblioref
|abbrev
|acronym
|citation
|citerefentry
|citetitle
|citebiblioid
|emphasis
|firstterm
|foreignphrase
|glossterm
|termdef
|footnote
|phrase
|orgname
|quote
|trademark
|wordasword
|personname
|link
|olink
|ulink
|action
|application
|classname
|methodname
|interfacename
|exceptionname
|ooclass
|oointerface
|ooexception
|package
|command
|computeroutput
|database
|envar
|errorcode
|errorname
|errortype
|errortext
|filename
|function
|guibutton
|guiicon
|guilabel
|guimenu
|guimenuitem
|guisubmenu
|hardware
|interface
|keycap
|keycode
|keycombo
|keysym
|literal
|code
|constant
|markup
|medialabel
|menuchoice
|mousebutton
|option
|optional
|parameter
|prompt
|property
|replaceable
|returnvalue
|sgmltag
|structfield
|structname
|symbol
|systemitem
|uri
|token
|type
|userinput
|varname
|nonterminal
|anchor
|author
|authorinitials
|corpauthor
|corpcredit
|modespec
|othercredit
|productname
|productnumber
|revhistory
|remark
|subscript
|superscript
|inlinegraphic
|inlinemediaobject
|inlineequation
|synopsis
|cmdsynopsis
|funcsynopsis
|classsynopsis
|fieldsynopsis
|constructorsynopsis
|destructorsynopsis
|methodsynopsis
|indexterm
|beginpage
|co
|coref
|lineannotation
|textobject
)*
Name | Type | Default | |||
width | CDATA | None | |||
linenumbering |
| None | |||
language | CDATA | None | |||
xml:space |
| None | |||
continuation |
| None | |||
format |
| "linespecific" | |||
startinglinenumber | CDATA | None |
A ProgramListing
is a verbatim environment for program source or
source fragment listings. 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 linebreaks within this element are significant. 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.
This element is displayed “verbatim”; whitespace and linebreaks within this element are significant.
The InterfaceDefinition
element will be discarded in DocBook V4.0. It will no longer be available
in the content model of this element.
These elements contain programlisting:
answer
, appendix
, article
, bibliodiv
, bibliography
, blockquote
, callout
, caption
, caution
, chapter
, colophon
, constraintdef
, dedication
, entry
, example
, figure
, footnote
, glossary
, glossdef
, glossdiv
, important
, index
, indexdiv
, informalexample
, informalfigure
, itemizedlist
, legalnotice
, listitem
, msgexplan
, msgtext
, note
, orderedlist
, para
, partintro
, preface
, procedure
, programlistingco
, qandadiv
, qandaset
, question
, refsect1
, refsect2
, refsect3
, refsection
, refsynopsisdiv
, revdescription
, sect1
, sect2
, sect3
, sect4
, sect5
, section
, setindex
, sidebar
, simplesect
, step
, taskprerequisites
, taskrelated
, tasksummary
, td
, textobject
, th
, tip
, variablelist
, warning
.
The following elements occur in programlisting:
abbrev
, acronym
, action
, anchor
, application
, author
, authorinitials
, beginpage
, biblioref
, citation
, citebiblioid
, citerefentry
, citetitle
, classname
, classsynopsis
, cmdsynopsis
, co
, code
, command
, computeroutput
, constant
, constructorsynopsis
, coref
, corpauthor
, corpcredit
, database
, destructorsynopsis
, email
, emphasis
, envar
, errorcode
, errorname
, errortext
, errortype
, exceptionname
, fieldsynopsis
, filename
, firstterm
, footnote
, footnoteref
, foreignphrase
, funcsynopsis
, function
, glossterm
, guibutton
, guiicon
, guilabel
, guimenu
, guimenuitem
, guisubmenu
, hardware
, indexterm
, inlineequation
, inlinegraphic
, inlinemediaobject
, interface
, interfacename
, keycap
, keycode
, keycombo
, keysym
, lineannotation
, link
, literal
, markup
, medialabel
, menuchoice
, methodname
, methodsynopsis
, modespec
, mousebutton
, nonterminal
, olink
, ooclass
, ooexception
, oointerface
, option
, optional
, orgname
, othercredit
, package
, parameter
, personname
, phrase
, productname
, productnumber
, prompt
, property
, quote
, remark
, replaceable
, returnvalue
, revhistory
, sgmltag
, structfield
, structname
, subscript
, superscript
, symbol
, synopsis
, systemitem
, termdef
, textobject
, token
, trademark
, type
, ulink
, uri
, userinput
, varname
, wordasword
, xref
.
The Format
attribute applies the
linespecific
notation to all ProgramListing
s.
All white space and line breaks must be preserved.
Line numbering indicates whether or not the lines
of a ProgramListing
are to be automatically numbered. The details
of numbering (every line or only selected lines, on the left or right, etc.)
are left up to the processing application. Be aware that not all processors
are capable of numbering lines.
Width
specifies the width (in characters)
of the longest line in this ProgramListing
(formatters may use
this value to determine scaling or rotation).