The AsciiDoc distribution includes a source filter for highlighting code syntax.
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).
You have the choice of three HTML source code highlighters, your selection is determined by the source-highlighter attribute (defaults to source-highlight):
|
Note |
Set the source-highlighter attribute from the asciidoc(1)
command-line or in the document header (not in the document body,
because the configuration file conditional macros are processed at
load time). |
The default highlighter is the GNU source-highlight which can highlight html4, html5 and xhtml11 outputs. The GNU source-highlight must be installed and the source-highlight command must reside in the shell search PATH.
You can use Highlight syntax highlighter for xhtml11, html5 and html4 outputs (set the source-highlighter attribute to highlighter).
The highlight command must reside in the shell search PATH.
To make Highlighter your default highlighter put the following line
your ~/.asciidoc/asciidoc.conf file:
source-highlighter=highlight
The AsciiDoc encoding attribute is passed to Highlighter using the
--encoding command-line option.
The Pygments syntax highlighter can be used for xhtml11 and html5 outputs (set the source-highlighter attribute to pygments).
The pygmentize command must reside in the shell search PATH.
You can customize Pygments CSS styles by editing
./stylesheets/pygments.css. The pygments.css CSS file was
generated with:
from pygments.formatters import HtmlFormatter
print HtmlFormatter().get_style_defs('.highlight')
To make Pygments your default highlighter put the following line
your ~/.asciidoc/asciidoc.conf file:
source-highlighter=pygments
The AsciiDoc encoding attribute is passed to Pygments using the
-O command-line option.
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.
Set to source.
The source code language name.
|
Note |
The language names vary between highlighters — consult the selected highlighter manual. |
Set to numbered to include line numbers.
Set tab size (GNU source-highlight only).
Include this attribute value in the highlighter command-line (HTML
outputs) or in the programlisting element (DocBook).
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 &
The source paragraph style will highlight a paragraph of source
code. These three code paragraphs:
|
Render this highlighted source code:
if n < 0: print 'Hello World!' |
if n < 0: print 'Hello World!' |
1: [true, false].cycle([0, 1, 2, 3, 4]) do |a, b|
2: puts "#{a.inspect} => #{b.inspect}" |
This source-highlight filtered block:
|
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:
|
Renders this highlighted source code:
1: #
2: # Useful Ruby base class extensions.
3: #
4:
5: class Array
6:
7: # Execute a block passing it corresponding items in
8: # +self+ and +other_array+.
9: # If self has less items than other_array it is repeated.
10:
11: def cycle(other_array) # :yields: item, other_item
12: other_array.each_with_index do |item, index|
13: yield(self[index % self.length], item)
14: end
15: end
16:
17: end
18:
19: if $0 == __FILE__ # <1>
20: # Array#cycle test
21: # true => 0
22: # false => 1
23: # true => 2
24: # false => 3
25: # true => 4
26: puts 'Array#cycle test' # <2>
27: [true, false].cycle([0, 1, 2, 3, 4]) do |a, b|
28: puts "#{a.inspect} => #{b.inspect}"
29: end
30: end |
First callout.
Second callout.
|
Tip |
|
Last updated 2002-11-25 00:37:42 UTC