1 <?xml version='1.0' encoding='UTF-8'?>
\r
2 <chapter xmlns="http://docbook.org/ns/docbook"
\r
3 xmlns:xi="http://www.w3.org/2001/XInclude"
\r
4 xmlns:xl="http://www.w3.org/1999/xlink"
\r
6 xml:id="programming">
\r
7 <title>Working with Code</title>
\r
10 <para>There are several instances when you will need to show code in documentation. You may need to use a class name, an interface name,
\r
11 or an element name as part of a sentence. You will also need to provide long code samples in many places. DocBook has a number of
\r
12 elements that are used for placing code in your documentation.</para>
\r
16 <title>Code Listings</title>
\r
17 <para>There are two types of code listings:</para>
\r
19 <listitem linkend="exampleSect">
\r
20 <para>Formal examples with titles</para>
\r
22 <listitem linkend="codeBlockSect">
\r
23 <para>Untitled code blocks</para>
\r
26 <para>Often when making long code listings a writer also needs to explain what specific lines of code do. This can be done using
\r
27 callouts as explained in <xref linkend="calloutSect" /></para>
\r
28 <section xml:id="exampleSect">
\r
29 <title>Examples</title>
\r
31 <title>When to use</title>
\r
32 <para>Examples are formal code listings that have a title. They are useful for code listings that are linked to from other places in
\r
33 the text. They are also added to the <emphasis>List of Examples</emphasis>.</para>
\r
36 <title>Marking up an example</title>
\r
37 <indexterm><primary>example element</primary></indexterm>
\r
38 <indexterm><primary>programlisting element</primary></indexterm>
\r
39 <para>Examples are marked up using the <tag class="element">example</tag> element. You should always provide a descriptive value for
\r
40 the <tag class="element">example</tag> element's <tag class="attribute">xml:id</tag> attribute. The
\r
41 <tag class="element">example</tag> element also takes a <tag class="attribute">pgwide</tag> attribute that signals that the
\r
42 code listing should span the width of the page.<footnote><para>The <tag class="attribute">pgwide</tag> attribute is not currently
\r
43 supported by the publication system. Writers will also need the PI for making code blocks wide as shown in
\r
44 <xref linkend="examplePgwideSS" />.</para></footnote></para>
\r
45 <para>The first child of the <tag class="element">example</tag> element is a <tag class="element">title</tag> element. The contents of
\r
46 the title element will be used as the caption of the example. It will also be used as the text for any cross references.</para>
\r
47 <para>The last child of the example element is the <tag class="element">programlisting</tag> element. The
\r
48 <tag class="element">programlisting</tag> element contains the code sample itself. Any text placed inside the
\r
49 <tag class="element">programlisting</tag> element is treated literally. Therefore, any spacing that you use will be exactly reproduced
\r
50 when the document is produced.</para>
\r
52 <para>When using XML inside a <tag class="element">programlisting</tag> element you must not use the <literal><</literal> or
\r
53 <literal>></literal> characters. Instead use <wordasword>&lt;</wordasword> and <wordasword>&gt;</wordasword>.</para>
\r
55 <para>The <tag class="element">programlisting</tag> element takes a <tag class="attribute">language</tag> attribute that
\r
56 specifies the type of code in the example. <xref linkend="languageAttrTbl"/> describes the acceptable values.</para>
\r
57 <table xml:id="languageAttrTbl">
\r
58 <title>Values for the Program Listing Language Attribute</title>
\r
62 <entry>Value</entry>
\r
63 <entry>Description</entry>
\r
68 <entry><tag class="attvalue">java</tag></entry>
\r
69 <entry>Specifies that the listing is Java code.</entry>
\r
72 <entry><tag class="attvalue">spring</tag></entry>
\r
73 <entry>Specifies that the listing is Spring XML. This is often used in configuration files.</entry>
\r
76 <entry><tag class="attvalue">wsdl</tag></entry>
\r
77 <entry>Specifies that the listing is WSDL.</entry>
\r
80 <entry><tag class="attvalue">xmlschema</tag></entry>
\r
81 <entry>Specifies that the code listing is XML Schema. This is often seen in the type's section of a WSDL document.</entry>
\r
84 <entry><tag class="attvalue">xml</tag></entry>
\r
85 <entry>Specifies that the code listing is XML.</entry>
\r
92 <title>Example</title>
\r
93 <para><xref linkend="example_example"/> shows the mark-up for an example.</para>
\r
94 <example xml:id="example_example" pgwide="1">
\r
96 <title>Example Mark-Up</title>
\r
97 <programlisting><example id="example_example">
\r
98 <title>Example Service</title>
\r
99 <programlisting language="java">public class ServiceName extends javax.xml.ws.Service
\r
102 public ServiceName(URL wsdlLocation, QName serviceName) { }
\r
104 public ServiceName() { }
\r
106 public Greeter getPortName() { }
\r
110 }</programlisting>
\r
111 </example></programlisting>
\r
113 <para>The mark-up shown in <xref linkend="example_example" /> is generated into <xref linkend="exampleExampleGen" />.</para>
\r
114 <example xml:id="exampleExampleGen">
\r
115 <title>Example Service</title>
\r
116 <programlisting language="java">public class ServiceName extends javax.xml.ws.Service
\r
119 public ServiceName(URL wsdlLocation, QName serviceName) { }
\r
121 public ServiceName() { }
\r
123 public Greeter getPortName() { }
\r
130 <simplesect xml:id="examplePgwideSS">
\r
131 <title>Making the example span the page</title>
\r
132 <para>The code used for an example does not always fit properly in the space allotted for text in the PDF output template. To fix this
\r
133 writers can specify that an example should span the entire page from the left margin to the right margin using the
\r
134 <markup><?dbfo pgwide="1"?></markup> PI.</para>
\r
135 <para>As shown in <xref linkend="examplePgwideEx"/>, the <markup><?dbfo pgwide="1"?></markup> PI is placed directly
\r
136 after the opening <tag class="element">example</tag> tag.</para>
\r
137 <example xml:id="examplePgwideEx">
\r
138 <?dbfo pgwide="1"?>
\r
139 <title>Wide Example Mark-Up</title>
\r
140 <programlisting><example id="examplePgwideEx">
\r
141 <?dbfo pgwide="1"?>
\r
142 <title>Example Service</title>
\r
143 <programlisting language="java">
\r
147 }</programlisting>
\r
148 </example></programlisting>
\r
152 <section xml:id="codeBlockSect">
\r
153 <title>Code Blocks</title>
\r
155 <title>When to use</title>
\r
156 <para>Code blocks are useful for short code listings that show a specific action. They are not appropriate for code listings
\r
157 that need to be referenced later. They also do not appear in the <emphasis>List of Examples</emphasis>.</para>
\r
160 <title>Mark-up</title>
\r
161 <indexterm><primary>informalexample element</primary></indexterm>
\r
162 <indexterm><primary>programlisting element</primary></indexterm>
\r
163 <para>Code blocks are marked up using the <tag class="element">informalexample</tag> element.</para>
\r
164 <para>The only child of the <tag class="element">informalexample</tag> element is a <tag class="element">programlisting</tag> element.
\r
165 This element contains the code listing itself. Any text placed inside the <tag class="element">programlisting</tag> element is
\r
166 treated literally. Therefore, any spacing that you use will be exactly reproduced when the document is produced.</para>
\r
168 <para>When using XML inside a <tag class="element">programlisting</tag> element you must not use the <literal><</literal> or
\r
169 <literal>></literal> characters. Instead use <wordasword>&lt;</wordasword> and <wordasword>&gt;</wordasword>.</para>
\r
171 <para>The <tag class="element">programlisting</tag> element takes a <tag class="attribute">language</tag> attribute that
\r
172 specifies the type of code in the example. <xref linkend="languageAttrTbl"/> describes the acceptable values.</para>
\r
175 <title>Example</title>
\r
176 <para><xref linkend="block_example"/> shows the mark-up for a standalone block of code.</para>
\r
177 <example xml:id="block_example" pgwide="1">
\r
178 <?dbfo pgwide="1"?>
\r
179 <title>Example Code Block</title>
\r
180 <programlisting><informalexample>
\r
181 <programlisting language="javascript">var WebServiceProvider1 = {
\r
182 'wsdlLocation': 'file:./wsdl/hello_world.wsdl',
\r
183 'serviceName': 'SOAPService1',
\r
184 'portName': 'SoapPort1',
\r
185 'targetNamespace': http://objectweb.org/hello_world_soap_http',
\r
186 };</programlisting>
\r
187 </informalexample></programlisting>
\r
189 <para>The mark-up shown in <xref linkend="block_example"/> would be published as follows:</para>
\r
191 <programlisting language="javascript">var WebServiceProvider1 = {
\r
192 'wsdlLocation': 'file:./wsdl/hello_world.wsdl',
\r
193 'serviceName': 'SOAPService1',
\r
194 'portName': 'SoapPort1',
\r
195 'targetNamespace': 'http://objectweb.org/hello_world_soap_http',
\r
196 };</programlisting>
\r
199 <simplesect xml:id="codeBlockPgwideSS">
\r
200 <title>Making the code block span the page</title>
\r
201 <para>Code listings do not always fit properly in the space allotted for text in the PDF output template. To fix this
\r
202 writers can specify that a code listing should span the entire page from the left margin to the right margin using the
\r
203 <markup><?dbfo pgwide="1"?></markup> PI.</para>
\r
204 <para>As shown in <xref linkend="codeBlockPgwideEx"/>, the <markup><?dbfo pgwide="1"?></markup> PI is placed directly
\r
205 after the opening <tag class="element">informalexample</tag> tag.</para>
\r
206 <example xml:id="codeBlockPgwideEx">
\r
207 <?dbfo pgwide="1"?>
\r
208 <title>Wide Code Block Mark-Up</title>
\r
209 <programlisting><informalexample id="codeBlockPgwideEx">
\r
210 <?dbfo pgwide="1"?>
\r
211 <programlisting language="java">
\r
215 }</programlisting>
\r
216 </informalexample></programlisting>
\r
220 <section xml:id="calloutSect">
\r
221 <title>Using Callouts</title>
\r
222 <indexterm><primary>co element</primary></indexterm>
\r
223 <indexterm><primary>calloutlist element</primary></indexterm>
\r
224 <para>It is often helpful to use callouts to explain what it happening in a section of code. Specifying callouts is a two step process:</para>
\r
227 <para>Specify where in the code listing you want to place callout markers.</para>
\r
230 <para>Specify the callout text for each callout.</para>
\r
234 <title>Specifying the callout locations</title>
\r
235 <para>To specify the placement of a callout in a program listing you place a <tag class="element">co</tag> element at the location inside of the program listing you want the callout to appear. The <tag class="element">co</tag> element requires that you set a value for its <tag class="attribute">id</tag> attribute. The value is used to associate the callout marker with the text that describes it. You should also provide a value for the <tag class="element">co</tag> element's <tag class="attribute">linkends</tag> attribute. This value will match the value of the <tag class="attribute">id</tag> attribute of the associated text. Using this attribute allows for a links to be generated between the callout and the associated text.</para>
\r
237 <para>Setting the <tag class="attribute">linkends</tag> attribute before entering the callout text will result in an invalid XML file. Once you add the callout text, the file should be valid.</para>
\r
241 <title>Specifying the callout text</title>
\r
242 <para>The text associated with a callout is specified outside of the <tag class="element">programlisting</tag> element and the <tag class="element">example</tag> element. Shortly after the <tag class="element">example</tag> element, preferably immediately after, you need to place a <tag class="element">calloutlist</tag> element. The <tag class="element">calloutlist</tag> element wraps the elements that specify the callout text. It contains an optional <tag class="element">title</tag> element and one <tag class="element">callout</tag> element for each callout specified for the associated program listing.</para>
\r
243 <para>Each <tag class="element">callout</tag> element must have its <tag class="attribute">arearefs</tag> attribute set to the value of <tag class="attribute">id</tag> attribute of the callout for which it defines the text. If you set the <tag class="attribute">linkends</tag> attribute of the associated <tag class="element">co</tag> element, you must also set the <tag class="element">callout</tag> element's <tag class="attribute">id</tag> attribute to the matching value. The callout text is the value of the <tag class="element">callout</tag> element.</para>
\r
246 <title>Example</title>
\r
247 <para><xref linkend="callout_example"/> shows the mark-up for <olink targetptr="LinksCalloutExample"/>.</para>
\r
248 <example xml:id="callout_example" pgwide="1">
\r
249 <?dbfo pgwide="1"?>
\r
250 <title>Using Callouts</title>
\r
251 <programlisting><example xml:id="LinksCalloutExample">
\r
252 <dbfo pgwide="1"?>
\r
253 <title>Document Set Site Map</title>
\r
254 <programlisting><?xml version="1.0" encoding="utf-8"?> <co linkends="sitemapptr0" xml:id="sitemapco0"/>
\r
255 <targetset> <co linkends="sitemapptr3" xml:id="sitemapco3"/>
\r
256 <targetsetinfo> <co linkends="sitemapptr4" xml:id="sitemapco4"/>
\r
257 Site map for the Evergreen XML Style Guide
\r
258 </targetsetinfo>
\r
259 <sitemap> <co linkends="sitemapptr5" xml:id="sitemapco5"/>
\r
260 <dir name="docs_rls_inferno"> <co linkends="sitemapptr6" xml:id="sitemapco6"/>
\r
261 <dir name="fluff"> <co linkends="sitemapptr75" xml:id="sitemapco75"/>
\r
262 <dir name="overview"> <co linkends="sitemapptr7" xml:id="sitemapco7"/>
\r
263 <document targetdoc="InfernoOverview"> <co linkends="sitemapptr8" xml:id="sitemapco8"/>
\r
264 <xi:include href="overview/target.db" xmlns:xi="http://www.w3.org/2001/XInclude" /> <co linkends="sitemapptr9" xml:id="sitemapco9"/>
\r
268 <dir name="install_guide">
\r
269 <document targetdoc="InfernoInstall">
\r
270 <xi:include href="install_guide/target.db" xmlns:xi="http://www.w3.org/2001/XInclude" />
\r
273 <dir name="getting_started">
\r
274 <document targetdoc="InfernoGetStarted">
\r
275 <xi:include href="get_started/target.db" xmlns:xi="http://www.w3.org/2001/XInclude" />
\r
280 </targetset></programlisting>
\r
282 <calloutlist>
\r
283 <title>Elements of the Site Map</title>
\r
284 <callout arearefs="sitemapco0" xml:id="sitemapptr0">
\r
285 <para>The site map should always be encoded as UTF-8. This ensures that all of the generated target data has the same encodings regardless of the encodings used by the XML source files.</para>
\r
287 <callout arearefs="sitemapco3" xml:id="sitemapptr3">
\r
288 <para>The <tag class="element">targetset</tag> element is the root of the site map.</para>
\r
290 <callout arearefs="sitemapco4" xml:id="sitemapptr4">
\r
291 <para>The <tag class="element">targetsetinfo</tag> element allows you to provide a description for the document set or any other information that is relevant to the site map.</para>
\r
293 <callout arearefs="sitemapco5" xml:id="sitemapptr5">
\r
294 <para>The <tag class="element">sitemap</tag> element contains the directory layout of the output files.</para>
\r
296 <callout arearefs="sitemapco6" xml:id="sitemapptr6">
\r
297 <para>The name of the top-level directory is not important in the generation of the target databases for the links. The links are generated relative to the top-level directory.</para>
\r
299 <callout arearefs="sitemapco75" xml:id="sitemapptr75">
\r
300 <para>This is a directory that only contains other directories.</para>
\r
302 <callout arearefs="sitemapco7" xml:id="sitemapptr7">
\r
303 <para>This directory holds a generated book.</para>
\r
305 <callout arearefs="sitemapco8" xml:id="sitemapptr8">
\r
306 <para>The <tag class="element">document</tag> element's <tag class="attribute">targetdoc</tag> attribute specifies the identifier used in the <tag class="element">olink</tag> element's <tag class="attribute">targetdoc</tag> attribute when linking to targets in the document.</para>
\r
308 <callout arearefs="sitemapco9" xml:id="sitemapptr9">
\r
309 <para>The target database is included in the site map using an <tag class="element">xi:include</tag> element. The path for each book's target database should be <filename><replaceable>book_src_dir</replaceable>/target.db</filename>.</para>
\r
311 </calloutlist></programlisting>
\r
316 <section xml:id="prog_arts">
\r
317 <title>In-line Code</title>
\r
319 <title>DocBook programming elements</title>
\r
320 <para>There are many instances where you need to place a code artifact in a block of text such as when you are referring to a Java class
\r
321 or an XML element. DocBook has a number of specialized elements for placing code artifacts in-line. The ones commonly used
\r
325 <para><tag class="element">tag</tag></para>
\r
328 <para><tag class="element">classname</tag></para>
\r
331 <para><tag class="element">interfacename</tag></para>
\r
334 <para><tag class="element">methodname</tag></para>
\r
337 <para><tag class="element">uri</tag></para>
\r
340 <para><tag class="element">package</tag></para>
\r
343 <para><tag class="element">code</tag></para>
\r
348 <title>XML artifacts</title>
\r
349 <para>When placing XML artifacts such as element names or attribute names in your text wrap them in an
\r
350 <tag class="element">tag</tag> element. To specify the type of XML artifact, the <tag class="element">tag</tag> element's
\r
351 <tag class="attribute">class</tag> attribute is always used. <xref linkend="class_values"/> shows the values used for the
\r
352 <tag class="attribute">class</tag> attribute.</para>
\r
353 <table xml:id="class_values">
\r
354 <title>Values for the <tag class="attribute">class</tag> Attribute</title>
\r
356 <colspec colwidth="1.5in"/>
\r
359 <entry>Value</entry>
\r
360 <entry>Description</entry>
\r
365 <entry><tag class="attvalue">attribute</tag></entry>
\r
366 <entry>Specifies that the artifact is an attribute of an XML element.</entry>
\r
369 <entry><tag class="attvalue">element</tag></entry>
\r
370 <entry>Specifies that the artifact is an XML element.</entry>
\r
373 <entry><tag class="attvalue">attvalue</tag></entry>
\r
374 <entry>Specifies that the artifact is the value of an XML element's attribute.</entry>
\r
377 <entry><tag class="attvalue">emptytag</tag></entry>
\r
378 <entry>Specifies an XML element that does not hold any data such as <tag class="emptytag">foo</tag>.</entry>
\r
385 <title>Web Addresses, URIs, and E-Mail Addresses</title>
\r
386 <para>To specify a Web address or URI you use the <tag class="element">uri</tag> element.</para>
\r
387 <para>To specify an E-Mail address use the <tag class="element">email</tag> element.</para>
\r
389 <simplesect xml:id="gen_prog_arts">
\r
390 <title>General programming language artifacts</title>
\r
391 <para>DocBook defines a number of in-line tags for specifying programming artifacts. The commonly used tags are listed in
\r
392 <xref linkend="progarti"/>.</para>
\r
393 <table frame="all" xml:id="progarti">
\r
394 <title>Elements for In-Line Programming Artifacts</title>
\r
396 <colspec colnum="1" colname="c1" colwidth="1.5in"/>
\r
397 <colspec colnum="2" colname="c2"/>
\r
400 <entry>Element</entry>
\r
401 <entry>Description</entry>
\r
406 <entry><tag class="element">type</tag></entry>
\r
407 <entry>Specifies that the artifact is a data type such as <type>int</type>.</entry>
\r
410 <entry><tag class="element">constant</tag></entry>
\r
411 <entry>Specifies that the artifact is a constant such as <constant>NULL</constant> or <constant>9</constant>.</entry>
\r
414 <entry><tag class="element">exceptionname</tag></entry>
\r
415 <entry>Specifies that the artifact is an exception. It could be the name of the exception or the name of the class that
\r
416 implements the exception.</entry>
\r
419 <entry><tag class="element">function</tag></entry>
\r
420 <entry>Specifies that the artifact is a function such as <function>println()</function>.</entry>
\r
423 <entry><tag class="element">parameter</tag></entry>
\r
424 <entry>Specifies that the artifact is a parameter to a function or a method.</entry>
\r
427 <entry><tag class="element">varname</tag></entry>
\r
428 <entry>Specifies that the artifact is a variable.</entry>
\r
431 <entry><tag class="element">code</tag></entry>
\r
432 <entry>Used for generic code entries that do not fit into any other category.</entry>
\r
435 <entry><markup>code role="annotation"</markup></entry>
\r
436 <entry>Used for Java annotations.</entry>
\r
443 <title>Object-oriented programming language artifacts</title>
\r
444 <para>In addition to the elements listed in <xref linkend="gen_prog_arts"/>, DocBook defines a number of elements that are used
\r
445 specifically for object-oriented programming artifacts. They are listed in <xref linkend="oo_arts"/>.</para>
\r
446 <table frame="all" xml:id="oo_arts">
\r
447 <title>Elements for In-Line OO Programming Artifacts</title>
\r
449 <colspec colnum="1" colname="c1" colwidth="1.5in"/>
\r
450 <colspec colnum="2" colname="c2"/>
\r
453 <entry>Element</entry>
\r
454 <entry>Description</entry>
\r
459 <entry><tag class="element">interfacename</tag></entry>
\r
460 <entry>Specifies that the artifact is a Java interface the user must implement.</entry>
\r
463 <entry><tag class="element">oointerface</tag></entry>
\r
464 <entry>Specifies that the artifact is a Java interface the user must implement. Requires the use of an <tag class="element">modifier</tag> element that contains details about if the interface is public or private.</entry>
\r
467 <entry><tag class="element">classname</tag></entry>
\r
468 <entry>Specifies that the artifact is a Java class or an instantiated object.</entry>
\r
471 <entry><tag class="element">ooclass</tag></entry>
\r
472 <entry>Specifies that the artifact is a Java class. Requires the use of an <tag class="element">modifier</tag> element that
\r
473 contains details about if the class is public/private or static/final.</entry>
\r
476 <entry><tag class="element">methodname</tag></entry>
\r
477 <entry>Specifies that the artifact is a method. Methods are different from functions in that methods are associated with classes and objects.</entry>
\r
480 <entry><tag class="element">ooexception</tag></entry>
\r
481 <entry>Specifies that the artifact is a Java exception. Requires the use of an <tag class="element">modifier</tag> element that
\r
482 contains details about if the exception is public or private.</entry>
\r
485 <entry><tag class="element">package</tag></entry>
\r
486 <entry>Specifies that the artifact is the name of a Java or C++ package.</entry>
\r
projects / Evergreen.git / blob