6.2.��Listing Code and Markups

A How-To Recipe

Jeff Elpern


Task

You need to show code listings or code fragments in reference material. This includes program language statement, scripts, macros, etc.

Or, you need to show XML structure in reference material. This includes such task as documenting the XML structure of data interchange formats or showing the markup required for DocBook.

Solution

The DocBook tag <programlisting> is used to identify a block of program code, script code, or XML data including DocBook Markup. Two solutions are presented below. The first is a listing of normal programming code. The second is an approach for code that has special characters, such as < and >, that conflict with DocBook markup.

Listing Code

Use <programlisting> tag to surround the block of code. This tag instructs the formating engine that the whitespace and line break in the block of text between the <programlisting> tags need to be maintained as is. In addition, the font style is defined as a fixed space character.

Example��1.��Markup for Program Listing

<programlisting>
/* --- DocBook styles ---------------------------------------
   conditional on being inside a DIV with:
       class="chapter" or class="appendix" or class="article"
  ----------------------------------------------------------- */

/* Root Chapter, Section and Article */
div.docbook {
  width: 700px;
  margin: 0px;
  padding: 0px;
  border-top: 0px dotted blue;
  border-bottom: 0px dotted blue;
  border-left: 0px dotted blue;
  border-right: 1px solid #D3D3D3;
}

....
</programlisting>

Publishes the following[1]:

/* --- DocBook styles ---------------------------------------
   conditional on being inside a DIV with:
       class="chapter" or class="appendix" or class="article"
  ----------------------------------------------------------- */

/* Root Chapter, Section and Article */
div.docbook {
  width: 700px;
  margin: 0px;
  padding: 0px;
  border-top: 0px dotted blue;
  border-bottom: 0px dotted blue;
  border-left: 0px dotted blue;
  border-right: 1px solid #D3D3D3;
}

....
         
[Note]Note

To avoid getting an extra blank line at the top and bottom of the listing area start the first line right after the <programlisting> tag and put the </programlisting> tag at the end of last line of text (see below).

<programlisting>10 PRINT "HELLO WORLD"
20 GOTO 10 </programlisting>

Listing DocBook Content and other XML Markup

One of the strengths of DocBook is the ability to annotate, highlight and place call-outs within program listings using DocBook tags. However, this means that while white space and end-of-line are maintained within a <programlisting> block, the formating engine is still looking for the angle brackets signifying a DocBook markup. This presents a real problem when presenting DocBook markup examples with a <programlisting> tag because the DocBook markup is full of tags that need to be display and not processed.

Two alternative exist: 1) change every angle bracket to a character code entity such as "&#62;" for >, or 2) use the CDATA markup to tell the formatter to display just as input.

<![CDATA[ ... ]]>

Example��2.��Markup for Listing DocBook Markup

The markup shown below:

<programlisting> <![CDATA[<emphasis>text</emphasis>]]> </programlisting>

Publishes the following where the <emphasis> tag is displayed:

<emphasis>text</emphasis>

Without the CDATA markup the DocBook fragment below:

<programlisting> <emphasis>text</emphasis> </programlisting>

Publishes the following:

text

As can be seen above the <emphasis> tag was interpreted as a formatting instruction which causes the text to be presented in italic.


Discussion

The <emphasis> has a number of attributes such as truning line numbers on (see programlisting Element Refererence in DocBook: The Definitive Guide

Example��3.��Program Listing with Line Numbers

Simple program listing with line numbers

<programlisting linenumbering="numbered">
10 PRINT "HELLO WORLD"
20 GOTO 10
</programlisting>

Publishes the following:

  1 10 PRINT "HELLO WORLD"
  2          20 GOTO 10 

Reference Material

Univ/CIE/KA/StrucDoc/HowToBookProto/ChapCode/listing (last edited 2015-03-06 18:11:26 by localhost)