1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
|
<refentry id="programlisting.element">
<?dbhtml filename="programlisting.html"?>
<refentryinfo>
<pubdate>$Date$</pubdate>
<releaseinfo>$Revision$</releaseinfo>
</refentryinfo>
<refmeta>
<indexterm><primary>elements</primary>
<secondary>programlisting</secondary></indexterm>
<refentrytitle>programlisting</refentrytitle>
<refmiscinfo>Element</refmiscinfo>
</refmeta>
<refnamediv>
<refname>programlisting</refname>
<refpurpose>&programlisting.purpose;</refpurpose>
</refnamediv>
&programlisting.synopsis.gen;
<refsect1 condition='ref.description'><title>Description</title>
<para>
A <sgmltag>ProgramListing</sgmltag> is a verbatim environment for program source or
source fragment listings. <sgmltag>ProgramListing</sgmltag>s are often placed
in <sgmltag>Example</sgmltag>s or <sgmltag>Figure</sgmltag>s so that they can be
cross-referenced from the text.
</para>
<refsect2><title>Processing Expectations</title>
<para>
&format.block; &pexp.linespecific; <sgmltag>ProgramListing</sgmltag>s are usually
displayed in a fixed width font.
</para>
<para>
Other markup within a <sgmltag>ProgramListing</sgmltag> 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 <glossterm>&CDATA; section</glossterm>:
<programlisting>
<![CDATA[
<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 >.
]]>
]]>
<![CDATA[
</programlisting>
]]>
</programlisting>
</para>
<para>
Two markup tags have
special significance in <sgmltag>ProgramListing</sgmltag>s: <sgmltag>CO</sgmltag>
and <sgmltag>LineAnnotation</sgmltag>.
A <sgmltag>CO</sgmltag> identifies the location of a <sgmltag>Callout</sgmltag>.
A <sgmltag>LineAnnotation</sgmltag> is a comment, added by the
<emphasis>documentor</emphasis>—not the programmer.
</para>
</refsect2>
<refsect2><title>Processing expectations</title>
<para>
&pexp.linespecific;
</para>
</refsect2>
<refsect2 role='fu' revision="4.0"><title>&FutureChanges;</title>
<para>
<!--do not index this occurance-->
&fu.interfacedefinition;
</para>
</refsect2>
<refsect2 role='fu' revision="5.0"><title>&FutureChanges;</title>
<para>The <literal>xml:space</literal> attribute is automatically
provided in the XML DTD.
</para>
</refsect2>
&programlisting.parents.gen;
&programlisting.children.gen;
</refsect1>
<refsect1 condition='ref.elem.attrdesc'><title>Attributes</title>
<variablelist>
<varlistentry><term>format</term>
<listitem>
<para>
The <sgmltag class="attribute">Format</sgmltag> attribute applies the
<literal>linespecific</literal> notation to all <sgmltag>ProgramListing</sgmltag>s.
All white space and line breaks must be preserved.
</para>
</listitem>
</varlistentry>
<varlistentry><term>linenumbering</term>
<listitem>
<para revision="4.0">Line numbering indicates whether or not the lines
of a <sgmltag>ProgramListing</sgmltag> 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.</para>
</listitem>
</varlistentry>
<varlistentry><term>width</term>
<listitem>
<para>
<sgmltag class="attribute">Width</sgmltag> specifies the width (in characters)
of the longest line in this <sgmltag>ProgramListing</sgmltag> (formatters may use
this value to determine scaling or rotation).
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 condition='ref.elem.seealso'><title>See Also</title>
&programlisting.seealso.gen;
</refsect1>
<refsect1><title>Examples</title>
&programlisting.example.seealso.gen;
</refsect1>
</refentry>
|
