Source Code Highlight Filter

The AsciiDoc distribution includes a source code syntax highlight filter (source-highlight-filter.conf).

HTML Outputs

The highlighter uses GNU source-highlight to highlight html4 and xhtml11 outputs. You also have the option of using the Pygments syntax highlighter for xhtml11 outputs.

To use Pygments you need to define an AsciiDoc attribute named pygments (either from the command-line or in the global asciidoc.conf configuration file) and you will also need to have Pygments installed and the pygmentize command in your PATH.

You can customize Pygments CSS styles by editing ./stylesheets/pygments.css.
To make Pygments your default highlighter put the following line your ~/.asciidoc/asciidoc.conf file:
```
pygments=
```
The AsciiDoc encoding attribute is passed to Pygments as a -O command-line option.

DocBook Outputs

DocBook outputs are highlighted by toolchains that have programlisting element highlight support, for example dblatex.

Examples

Source code paragraphs

The source paragraph style will highlight a paragraph of source code. These three code paragraphs:

if n < 0: print 'Hello World!'

:language: python


if n < 0: print 'Hello World!'


[true, false].cycle([0, 1, 2, 3, 4]) do |a, b|
    puts "#{a.inspect} => #{b.inspect}"

Render this highlighted source code:

if n < 0: print 'Hello World!'

if n < 0: print 'Hello World!'

00001: [true, false].cycle([0, 1, 2, 3, 4]) do |a, b|
00002:     puts "#{a.inspect} => #{b.inspect}"

Unnumbered source code listing

This source-highlight filtered block:

 
 ---------------------------------------------------------------------
 ''' A multi-line
     comment.'''
 def sub_word(mo):
     ''' Single line comment.'''
     word = mo.group('word')   # Inline comment
     if word in keywords[language]:
         return quote + word + quote
     else:
         return word
 ---------------------------------------------------------------------

Renders this highlighted source code:

''' A multi-line
    comment.'''
def sub_word(mo):
    ''' Single line comment.'''
    word = mo.group('word')     # Inline comment
    if word in keywords[language]:
        return quote + word + quote
    else:
        return word

Numbered source code listing with callouts

This source-highlight filtered block:

 
 ---------------------------------------------------------------------
 #
 # Useful Ruby base class extensions.
 #

 class Array

   # Execute a block passing it corresponding items in
   # +self+ and +other_array+.
   # If self has less items than other_array it is repeated.

   def cycle(other_array)  # :yields: item, other_item
     other_array.each_with_index do |item, index|
       yield(self[index % self.length], item)
     end
   end

 end

 if $0 == __FILE__                                 <1>
   # Array#cycle test
   # true => 0
   # false => 1
   # true => 2
   # false => 3
   # true => 4
   puts 'Array#cycle test'                         <2>
   [true, false].cycle([0, 1, 2, 3, 4]) do |a, b|
     puts "#{a.inspect} => #{b.inspect}"
   end
 end
 ---------------------------------------------------------------------

 <1> First callout.
 <2> Second callout.

Renders this highlighted source code:

00001: #
00002: # Useful Ruby base class extensions.
00003: #
00004:
00005: class Array
00006:
00007:   # Execute a block passing it corresponding items in
00008:   # +self+ and +other_array+.
00009:   # If self has less items than other_array it is repeated.
00010:
00011:   def cycle(other_array)  # :yields: item, other_item
00012:     other_array.each_with_index do |item, index|
00013:       yield(self[index % self.length], item)
00014:     end
00015:   end
00016:
00017: end
00018:
00019: if $0 == __FILE__                                 <1>
00020:   # Array#cycle test
00021:   # true => 0
00022:   # false => 1
00023:   # true => 2
00024:   # false => 3
00025:   # true => 4
00026:   puts 'Array#cycle test'                         <2>
00027:   [true, false].cycle([0, 1, 2, 3, 4]) do |a, b|
00028:     puts "#{a.inspect} => #{b.inspect}"
00029:   end
00030: end

First callout.
Second callout.

Tip

If the source language attribute has been set (using an AttributeEntry or from the command-line) you don’t have to specify it in each source code block.
You may need to place callout markers inside source code comments to ensure they are not misinterpreted and mangled by the highlighter.

Installation

HTML

If you want to syntax highlight AsciiDoc HTML outputs (html4 and xhtml11 backends) you need to install GNU source-highlight or Pygments (most distributions have these packages).

DocBook

AsciiDoc encloses the source code in a DocBook programlisting element and leaves source code highlighting to the DocBook toolchain (dblatex has a particularly nice programlisting highlighter). The DocBook programlisting element is assigned two attributes:

The language attribute is set to the AsciiDoc language attribute.
The linenumbering attribute is set to the AsciiDoc src_numbered attribute (numbered or unnumbered).

Testing

Test the filter by converting the test file to HTML with AsciiDoc:

$ asciidoc -v ./filters/source/source-highlight-filter-test.txt
$ firefox ./filters/source/source-highlight-filter-test.html &

Stuart's Notes