programlisting
Prev | DocBook Element Reference | Next

This is an alpha version of this book.

# programlisting

## Name

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

##

# Synopsis

### Mixed Content Model

    programlisting ::=
    (#PCDATA|footnoteref|xref|abbrev|acronym|citation|citerefentry|
     citetitle|emphasis|firstterm|foreignphrase|glossterm|footnote|
     phrase|quote|trademark|wordasword|link|olink|ulink|action|
     application|classname|methodname|interfacename|exceptionname|
     ooclass|oointerface|ooexception|command|computeroutput|database|
     email|envar|errorcode|errorname|errortype|filename|function|
     guibutton|guiicon|guilabel|guimenu|guimenuitem|guisubmenu|
     hardware|interface|keycap|keycode|keycombo|keysym|literal|
     constant|markup|medialabel|menuchoice|mousebutton|option|
     optional|parameter|prompt|property|replaceable|returnvalue|
     sgmltag|structfield|structname|symbol|systemitem|token|type|
     userinput|varname|nonterminal|anchor|author|authorinitials|
     corpauthor|modespec|othercredit|productname|productnumber|
     revhistory|remark|subscript|superscript|inlinegraphic|
     inlinemediaobject|inlineequation|synopsis|cmdsynopsis|
     funcsynopsis|classsynopsis|fieldsynopsis|constructorsynopsis|
     destructorsynopsis|methodsynopsis|indexterm|beginpage|co|
     lineannotation)*

### Attributes

Common attributes

Name | Type | Default
width | CDATA | None
format | Enumerated notation:
linespecific
| "linespecific"
linenumbering | Enumeration:
numbered
unnumbered
| None

### Parameter Entities

The following parameter entities contain programlisting:

Parameter Entities
`%admon.mix;` | `%bookcomponent.content;` | `%component.mix;`
`%divcomponent.mix;` | `%example.mix;` | `%figure.mix;`
`%footnote.mix;` | `%glossdef.mix;` | `%indexdivcomponent.mix;`
`%legalnotice.mix;` | `%linespecific.class;` | `%para.mix;`
`%qandaset.mix;` | `%refcomponent.mix;` | `%revdescription.mix;`
`%sidebar.mix;` | `%tabentry.mix;` | `%tbl.entry.mdl;`
`%textobject.mix;` |  |

## Description

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.

### Processing Expectations

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.

### Processing expectations

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

### Future Changes

The `InterfaceDefinition` element will be discarded in DocBook V4.0. It will no longer be available in the content model of this element.

### Future Changes

The `xml:space` attribute is automatically provided in the XML DTD.

### Parents

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`, `legalnotice`, `listitem`, `msgexplan`, `msgtext`, `note`, `para`, `partintro`, `preface`, `procedure`, `programlistingco`, `qandadiv`, `qandaset`, `question`, `refsect1`, `refsect2`, `refsect3`, `refsynopsisdiv`, `revdescription`, `sect1`, `sect2`, `sect3`, `sect4`, `sect5`, `section`, `setindex`, `sidebar`, `simplesect`, `step`, `textobject`, `tip`, `warning`.

### Children

The following elements occur in programlisting: `abbrev`, `acronym`, `action`, `anchor`, `application`, `author`, `authorinitials`, `beginpage`, `citation`, `citerefentry`, `citetitle`, `classname`, `classsynopsis`, `cmdsynopsis`, `co`, `command`, `computeroutput`, `constant`, `constructorsynopsis`, `corpauthor`, `database`, `destructorsynopsis`, `email`, `emphasis`, `envar`, `errorcode`, `errorname`, `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`, `othercredit`, `parameter`, `phrase`, `productname`, `productnumber`, `prompt`, `property`, `quote`, `remark`, `replaceable`, `returnvalue`, `revhistory`, `sgmltag`, `structfield`, `structname`, `subscript`, `superscript`, `symbol`, `synopsis`, `systemitem`, `token`, `trademark`, `type`, `ulink`, `userinput`, `varname`, `wordasword`, `xref`.

## Attributes

format

  The `Format` attribute applies the `linespecific` notation to all `ProgramListing`s. All white space and line breaks must be preserved.

linenumbering

  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

  `Width` specifies the width (in characters) of the longest line in this `ProgramListing` (formatters may use this value to determine scaling or rotation).

## See Also

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

## Examples

For examples, see `example`, `informalexample`, `programlistingco` .

Prev | Home | Next
productnumber | Up | programlistingco

Copyright © 1999, 2000, 2001 O'Reilly & Associates, Inc.