Source Code Highlight Filter

Installation

As a prerequisite you will have installed and tested GNU source-highlight. See Appendix A for Kubuntu installation.

Now install the AsciiDoc filter:

Copy the filter (./examples/source-highlight-filter/source-hightlight-filter.conf) to one of the standard AsciiDoc filter locations — typically /etc/asciidoc/filters/ or ~/.asciidoc/filters/.

Warning
As will all filters, before installing, you should verify that they can't be coerced into generating malicious output or exposing sensitive information.

Test it by converting this file to HTML with AsciiDoc:

$ cd ./examples/source-highlight-filter
$ asciidoc source-highlight-filter.txt

DocBook Output Definition file

Note	As of Source-highlight 2.3 the AsciiDoc DocBook output definition file has been included in the Source-highlight distribution so you can skip this section if you have version 2.3 or greater.

Source-highlight 2.2 does not ship with DocBook output definition files. If you want to generate DocBook instead of HTML the following simple DocBook output definition file will do the trick:

extension "xml"

bold "<emphasis role=\"strong\">$text</emphasis>"
italics "<emphasis>$text</emphasis>"

translations
"&" "&amp;"
"<" "&lt;"
">" "&gt;"
end

To install it:

Name it docbook.outlang and copy it to the source-highlight configuration files directory (typically /usr/local/share/source-highlight/).
Add the following line to /usr/local/share/source-highlight/outlang.map:
```
docbook = docbook.outlang
```

Examples

Example: Python code snippet

This source-highlight filtered block:

[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

Example: Ruby code snippet with line numbering

This source-highlight filtered block:

[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__
  # Array#cycle test
  # true => 0
  # false => 1
  # true => 2
  # false => 3
  # true => 4
  puts 'Array#cycle test'
  [true, false].cycle([0, 1, 2, 3, 4]) do |a, b|
    puts "#{a.inspect} => #{b.inspect}"
  end
end
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Renders this highlighted source code:

00001: #
00002: # Useful Ruby base class tension's.
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

Appendix A: Installing source-highlight 2.2 on Kubuntu 5.0.4

The 5.0.4 repository only had the older version 1.6.3 so I downloaded version 2.2 source and compiled — but first had to install boost regular expression libraries:

# apt-get install libboost-regex1.31.0
# apt-get install libboost-dev
# apt-get install libboost-regex-dev
# apt-get install exuberant-ctags

Download, compile and install source-highlight:

$ tar -xzf source-highlight-2.2.tar.gz
$ cd source-highlight-2.2
$ ./configure
$ make
$ su
# make install