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