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.

The filter command must reside in the shell search PATH. pygmentize command in your PATH.
To use Pygments you need to define an AsciiDoc attribute named pygments.
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

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).

Block attributes

The following attributes can be included in source code block attribute lists.

style and language are mandatory.
style, language and src_numbered are the first three positional attributes in that order.
The args attribute allows the inclusion of arbitrary (highlighter dependent) command options.

style: Set to source.
language: The source code language name.
src_numbered: Set to numbered to include line numbers.
src_tab: Set tab size (GNU source-highlight only).
args: Include this attribute value in the highlighter command-line (GNU source-highlight and pygmentize) or in the programlisting element (DocBook).

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 &

Examples

Source code paragraphs

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

[source,python]
if n < 0: print 'Hello World!'

:language: python

[source]
if n < 0: print 'Hello World!'

[source,ruby,numbered]
[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:

 [source,python]
 ---------------------------------------------------------------------
 ''' 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:

 [source,ruby,numbered]
 ---------------------------------------------------------------------
 #
 # 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__                                 
00020:   # Array#cycle test
00021:   # true => 0
00022:   # false => 1
00023:   # true => 2
00024:   # false => 3
00025:   # true => 4
00026:   puts 'Array#cycle test'                         
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.

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.