Source Code Highlight Filter
============================

The AsciiDoc distribution includes a source code syntax highlight
filter (`source-highlight-filter.conf`) which uses
http://www.gnu.org/software/src-highlite/[GNU source-highlight]. GNU
source-highlight generates nicely formatted source code for most
common programming languages (see the <<X1,examples below>>).

Installation
------------
As a prerequisite you will have installed and tested
http://www.gnu.org/software/src-highlite/[GNU source-highlight]. See
<<X2,Appendix A>> for Kubuntu installation.

Now install the AsciiDoc filter:

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

2. 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:

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

   docbook = docbook.outlang


[[X1]]
Examples
--------
.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:

[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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
=====================================================================


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

[ruby,numbered]
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
#
# Useful Ruby base class tension's.
#

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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
=====================================================================


[[X2]]
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
---------------------------------------------------------------------

