# Source Code Highlight Filter

The AsciiDoc distribution includes a source code syntax highlight filter (`source-highlight-filter.conf`). It uses GNU source-highlight to highlight HTML outputs; DocBook outputs are highlighted by toolchains that have `programlisting` element highlight support, for example dblatex.

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.

## 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__                                 <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

1. First callout.

2. Second callout.

## Installation

### HTML

If you want to syntax highlight AsciiDoc HTML outputs (`html4` and `xhtml11` backends) you need to install GNU source-highlight (most distributions have this package).

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

1. The language attribute is set to the AsciiDoc language attribute.

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

If you use ``a2x(1)`` to generate PDF you need to include the `--no-xmllint` option to suppress `xmllint(1)` checking — the programlisting language attribute (required by the dblatex source highlighter) is not part of the DocBook 4 specification (but it is in the newer DocBook 5 specification).

### Testing

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

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

Last updated 2009-01-01 12:22:58 NZDT