← Back to branch summary

~ubuntu-branches/ubuntu/utopic/asciidoc/utopic

« back to all changes in this revision

Viewing changes to doc/source-highlight-filter.txt

  • Committer: Bazaar Package Importer
  • Author(s): Alexander Wirt
  • Date: 2010-11-27 23:19:57 UTC
  • mfrom: (1.1.12 upstream) (3.1.6 sid)
  • Revision ID: james.westby@ubuntu.com-20101127231957-jxdmrk7z7lkcqy3l
Tags: 8.6.3-1
http://bugs.debian.org/595324
http://bugs.debian.org/526351
http://bugs.debian.org/571303
http://bugs.debian.org/592423
http://bugs.debian.org/499497
http://bugs.debian.org/564015
* New upstream version (Closes: #595324)
* Support asciidoc API (Closes: #526351)
* Depend on python >= 2.4 (Closes: #571303)
* Do not compress .txt files (Closes: #592423)
* Enhance asciidoc manpage (Closes: #499497)
* Move some of the Recommends (vim-addon-manager, source-highlight) to 
  Suggests (Closes: #564015)
* Bump standards version (No changes)
* Add README.Source file

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/source-highlight-filter.txt
2
2
============================
3
3
 
4
4
The AsciiDoc distribution includes a source code syntax highlight
5
 
filter (`source-highlight-filter.conf`). It uses
6
 
http://www.gnu.org/software/src-highlite/[GNU source-highlight] to
7
 
highlight HTML outputs; DocBook outputs are highlighted by toolchains
8
 
that have `programlisting` element highlight support, for example
9
 
'dblatex'.
10
 
 
11
 
TIP: If the source 'language' attribute has been set (using an
12
 
'AttributeEntry' or from the command-line) you don't have to specify
13
 
it in each source code block.
 
5
filter (`source-highlight-filter.conf`).
 
6
 
 
7
 
 
8
HTML Outputs
 
9
------------
 
10
The highlighter uses http://www.gnu.org/software/src-highlite/[GNU
 
11
source-highlight] to highlight 'html4' and 'xhtml11' outputs. You also
 
12
have the option of using the http://pygments.org/[Pygments] syntax
 
13
highlighter for 'xhtml11' outputs.
 
14
 
 
15
To use Pygments you need to define an AsciiDoc attribute named
 
16
'pygments' (either from the command-line or in the global
 
17
`asciidoc.conf` configuration file) and you will also need to have
 
18
Pygments installed and the 'pygmentize' command in your PATH.
 
19
 
 
20
- You can customize Pygments CSS styles by editing
 
21
  `./stylesheets/pygments.css`.
 
22
- To make Pygments your default highlighter put the following line
 
23
  your `~/.asciidoc/asciidoc.conf` file:
 
24
 
 
25
  pygments=
 
26
 
 
27
- The AsciiDoc 'encoding' attribute is passed to Pygments as a `-O`
 
28
  command-line option.
 
29
 
 
30
 
 
31
DocBook Outputs
 
32
---------------
 
33
DocBook outputs are highlighted by toolchains that have
 
34
`programlisting` element highlight support, for example 'dblatex'.
14
35
 
15
36
 
16
37
Examples
17
38
--------
 
39
 
18
40
Source code paragraphs
19
41
~~~~~~~~~~~~~~~~~~~~~~
20
42
The `source` paragraph style will highlight a paragraph of source
166
188
<1> First callout.
167
189
<2> Second callout.
168
190
 
 
191
[TIP]
 
192
=====
 
193
- If the source 'language' attribute has been set (using an
 
194
  'AttributeEntry' or from the command-line) you don't have to specify
 
195
  it in each source code block.
 
196
- You may need to place callout markers inside source code comments to
 
197
  ensure they are not misinterpreted and mangled by the highlighter.
 
198
=====
 
199
 
169
200
 
170
201
Installation
171
202
------------
172
203
HTML
173
204
~~~~
174
205
If you want to syntax highlight AsciiDoc HTML outputs (`html4` and
175
 
`xhtml11` backends) you need to
176
 
install http://www.gnu.org/software/src-highlite/[GNU
177
 
source-highlight] (most distributions have this package).
 
206
`xhtml11` backends) you need to install
 
207
http://www.gnu.org/software/src-highlite/[GNU source-highlight] or
 
208
http://pygments.org/[Pygments] (most distributions have these
 
209
packages).
178
210
 
179
211
DocBook
180
212
~~~~~~~