1.7. Incorporating Code Listings

1.7. Incorporating Code Listings
Prev	Chapter 1. Knowing DocBook’s Structure	Next

Difficulty: ★★☆ (medium)

Keywords: programlistings, code

Problem

You need to add an element that is used for code listings.

Solution

Use the programlisting element. For example, the following markup shows some Python code:

<programlisting>#!/usr/bin/python

def sayhello(name):
  """Say hello to someone"""
  return "Hello %s" % name

sayhello("Tux")</programlisting>

If you want to benefit from syntax highlighting later, add the language attribute:

<programlisting language="python">...</programlisting>

Discussion

In most cases, programlisting is probably enough for all your needs. However, the DocBook stylesheets and the DocBook extension support some convenient features you should know:

Annotated lines for short comments
Callouts, for more exhaustive explanations
Line numbering, if referring to a number is sufficient
External code files, if you want to incorporate files from outside your DocBook document

The above features are explained in the following subsections.

Using Line Annotatations

Annotated lines are short comments created by lineannotation:

<programlisting>#!/usr/bin/python <lineannotation>She-bang line</lineannotation>

def sayhello(name):
  """Say hello to someone""" <lineannotation>Python's doc comment</lineannotation>
  return "Hello %s" % name

sayhello("Tux")
</programlisting>

Line annotations are printed in italic by default:

#!/usr/bin/python Shebang line

def sayhello(name):
  """Say hello to someone""" Python's doc comment
  return "Hello %s" % name

sayhello("Tux")

They are only useful, if you have short comments. If you need further explanations, callouts are better suited for this task.

Problems can arise when a reader wants to copy and paste text containing line annotations. Such text usually creates syntax problems. In this case, use a comment symbol for the appropriate programming language. For Python, it is the hash sign that can be combined in a programlisting context as follows:

<programlisting> ...
# <lineannotation>Function to output a warm welcome message</lineannotation>
def sayhello(name):
  ...
</programlisting>

With this method, an annotated line does not create any syntax errors.

Using Callouts

toms, 2012-09-02: Refer to its own topic

Callouts are little marks in your code that refer to a more exhaustive explanation, usually after the code. Such an explanation is marked up as a calloutlist:

<programlisting language="python"
>#!/usr/bin/python <co xml:id="co.shebang"/>

def sayhello(name):
  """Say hello to someone""" <co xml:id="co.doccomment"/>
  return "Hello %s" % name

sayhello("Tux")</programlisting>
<calloutlist>
   <callout arearefs="co.shebang">
     <para>A Shebang line. Unix-like operating systems can parse
           this line, execute the corresponding interpreter and pass
           the script as first argument.</para>
   </callout>
   <callout arearefs="co.doccomment">
     <para>A Python doc comment. Usually, written as triple quotes
           or as triple apostrophes marking the doc comment for a function
           or class.</para>
   </callout>
</calloutlist>

The result will look like this:

#!/usr/bin/python 

def sayhello(name):
  """Say hello to someone""" 
  return "Hello %s" % name

sayhello("Tux")

	A Shebang line. Unix-like operating systems can parse this line, execute the corresponding interpreter and pass the script as first argument.
	A Python doc comment. Usually, written as triple quotes or as triple apostrophes marking the doc comment for a function or class.

Callouts are a good way to give your reader more explanations. Find more information in TODO: Add xref.

Setting Line Numbering

Numbering program listings can be done with the attribute linenumbering:

<programlisting linenumbering="numbered">...

The result can look like this:

 1 | #!/usr/bin/python
 2 |
 3 | def sayhello(name):
 4 | """Say hello to someone"""
 5 | return "Hello %s" % name
 6 |
 7 | sayhello("Tux")

There are several ways to influence the numbering using DocBook and the DocBook stylesheets:

startinglinenumber: This attribute in <programlisting> specifies the initial line number.
continuation: This attribute in <programlisting> determines whether line numbering continues from the previous element or restarts. Possible values are continues or restarts (default).
<?dbhtml linenumbering.everyNth="N"?>, <?dbfo linenumbering.everyNth="N"?>: These processing instructions (PI) specify intervals for line numbers. By default, every 5th line displays its number.
<?dbhtml linenumbering.separator="text"?>, <?dbfo linenumbering.separator="text"?>: These PIs specify separators for line numbers. By default it is a single space. It is printed after the line number but before the line from the program listing.
<?dbhtml linenumbering.width="width"?>, <?dbfo linenumbering.width="width"?>: These PIs specifiy the width for line numbers. By default, this value is set to three which gives you a reserved space of numbers up to 999.
linenumbering.extension: Parameter that enables the line numbering extension

To use the processing instructions, add them in programlisting without any whitespace:

<programlisting><?dbhtml
   linenumbering.everyNth="2"
   linenumbering.width="2" ?>#!/usr/bin/python
...
</programlisting>

This will create the following output:

  | #!/usr/bin/python
 2|
  | def sayhello(name):
 4| """Say hello to someone"""
  | return "Hello %s" % name
 6|
  | sayhello("Tux")

Incorporating External Files

To incorporate external files is explained in a separate topic. Refer to Section 1.8, “Incorporating External Files in Code Listings”.

Prev	Up	Next
1.6. Using Lists	Home	1.8. Incorporating External Files in Code Listings