$ cd ./examples/source-highlight-filter $ asciidoc source-highlight-filter.txt
The AsciiDoc distribution includes a source code syntax highlight filter (source-highlight-filter.conf) which uses GNU source-highlight. GNU source-highlight generates nicely formatted source code for most common programming languages (see the examples below).
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
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 "&" "&" "<" "<" ">" ">" 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
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
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
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