Permalink
Browse files

updates syntax highlighting examples

- adds pygments attributes and example snippet
- adds coderay section
- adds coderay attributes
- adds pygments output image
- closes asciidoctor#162
- closes asciidoctor/asciidoctor#637
- documents asciidoctor/asciidoctor#604
  • Loading branch information...
graphitefriction committed Jul 16, 2014
1 parent 3a67aa5 commit 65e308b765e21f777681119d872e07d170aa0593
@@ -0,0 +1,96 @@
////
Included in:
- user-manual: Source Code Highlighting: CodeRay installation
:coderay-uri:
:coderay-gem: https://rubygems.org/gems/coderay
////
{coderay-uri}[CodeRay] is an encoding-aware, syntax highlighter that supports the languages listed below.
[cols=3,grid=none,frame=none]
|===
| C
| C++
| Clojure
| CSS
| Delphi
| diff
| ERB
| Go
| Groovy
| HAML
| HTML
| Java
| JavaScript
| JSON
| Lua
| PHP
| Python
| Ruby
| Sass
| SQL
| Taskpaper
| XML
| YAML
|
|===
In order to use CodeRay with Asciidoctor, you need the {coderay-gem}[coderay RubyGem].
.Installing the CodeRay RubyGem via the CLI
[source,console]
....
$ gem install coderay
....
Once you've installed the RubyGem, assign +coderay+ to the +source-highlighter+ attribute in your document's header.
[source]
----
:source-highlighter: coderay
----
You can further customize the source block output with additional CodeRay attributes.
[horizontal]
coderay-css::
Controls what method is used for applying CSS to the tokens. Can be `class` or `style`. Default: `class`.
coderay-linenums-mode::
Controls how line numbers are laid out. Can be `table` or `inline`. Default: `table`.
.Customizing a source block with CodeRay line numbers
[source]
....
:source-highlighter: coderay
:coderay-linenums-mode: inline
[source,ruby,linenums]
----
ORDERED_LIST_KEYWORDS = {
'loweralpha' => 'a',
'lowerroman' => 'i',
'upperalpha' => 'A',
'upperroman' => 'I'
#'lowergreek' => 'a'
#'arabic' => '1'
#'decimal' => '1'
}
----
....
See the <<user-manual#hl-css,CodeRay stylesheet section>> to learn about the `coderay-css` attribute.
////
Note: I'm not getting this to work. Need to come back and do some quality assurance.
////
@@ -2,18 +2,70 @@
Included in:
- user-manual: Source Code Syntax Highlighting: Pygments installation
:pygments-gem: https://rubygems.org/gems/pygments.rb
:pygments-lang: http://pygments.org/languages/
////
The most popular source code highlighter in the AsciiDoc world, perhaps even the whole world, is {pygments-org}[Pygments].
{pygments-org}[Pygments] is a popular syntax highlighter that supports a broad range of {pygments-lang}[programming, template and markup languages].
In order to use Pygments with Asciidoctor, you need to install Pygments (and Python, if you don't have it yet).
You then need to install the pygments.rb RubyGem.
In order to use Pygments with Asciidoctor, you need Python, pygments.py, and the {pygments-gem}[pygments.rb RubyGem].
$ "`\which apt-get || \which yum || \which brew`" install pygments
$ gem install pygments.rb
.Installing Pygments and the Pygments RubyGem via the CLI
[source,console]
....
$ "`\which apt-get || \which yum || \which brew`" install pygments // <1>
$ gem install pygments.rb // <2>
....
<1> Install the python implementation of Pygments using your package manager.
<2> Install the Pygments RubyGem.
To activate it in Asciidoctor, assign the value +pygments+ to the +source-highlighter+ attribute in your document's header.
Once you've installed the RubyGem, assign +pygments+ to the +source-highlighter+ attribute in your document's header.
[source]
----
:source-highlighter: pygments
----
You can further customize the source block output with additional Pygments attributes.
[horizontal]
pygments-style::
Sets the name of the color theme Pygments uses. Default: `pastie`.
pygments-css::
Controls what method is used for applying CSS to the tokens. Can be `class` or `style`. Default: `class`.
pygments-linenums-mode::
Controls how line numbers are laid out. Can be `table` or `inline`. Default: `table`.
.Customizing a source block with Pygments attributes
[source]
....
:source-highlighter: pygments
:pygments-style: manni
:pygments-linenums-mode: inline
[source,ruby,linenums]
----
ORDERED_LIST_KEYWORDS = {
'loweralpha' => 'a',
'lowerroman' => 'i',
'upperalpha' => 'A',
'upperroman' => 'I'
#'lowergreek' => 'a'
#'arabic' => '1'
#'decimal' => '1'
}
----
....
.Rendered source block using inline line numbers and the manni theme
====
image::custom-pygments.png[Line numbers and a custom Pygments theme for a source block.]
====
[INFORMATION]
====
Type `pygmentize -L styles` in your CLI to see a list of the Pygments styles you have installed.
====
See the <<user-manual#hl-css,Pygments stylesheet section>> to learn about the `pygments-css` attribute.
@@ -30,7 +30,7 @@ Asciidoctor supports a number of syntax highlighting libraries.
|pygments
|===
Once you've set the attribute and library value, set the block style to source and specify the source language in the second attribute position.
Once you've set the attribute and library, assign +source+ to the block and specify the source language in the second attribute position.
.Example
....
@@ -313,6 +313,16 @@ d|+$$[*]$$+, +$$[X]$$+ (checked)
|{y}
|
|coderay-css
|{n}
|{y}
|
|coderay-linenums-mode
|{n}
|{y}
|
|colophon
|{y}
|{y}
@@ -1133,6 +1143,21 @@ d|+preamble+ (ToC)
|{y}
|
|pygments-css
|{n}
|{y}
|
|pygments-linenums-mode
|{n}
|{y}
|
|pygments-style
|{n}
|{y}
|
|q
|{n}
|{y}
@@ -1,7 +1,7 @@
= Asciidoctor User Manual
Sarah White <https://github.com/graphitefriction[@graphitefriction]>; Dan Allen <https://github.com/mojavelinux[@mojavelinux]>
:description: This guide describes the Asciidoctor attributes, values, and layout options available for producing a customized and polished document.
:keywords: AsciiDoc, Asciidoctor, syntax, reference, learn, how to, AsciiMath, LaTeXMath, MathJax
:keywords: AsciiDoc, Asciidoctor, syntax, reference, learn, how to, AsciiMath, LaTeXMath, MathJax, Pygments, CodeRay
:doctype: book
:toc: right
:toclevels: 2
@@ -20,7 +20,7 @@ Sarah White <https://github.com/graphitefriction[@graphitefriction]>; Dan Allen
:y: icon:ok[role="green"]
:n: icon:remove[role="red"]
:c: icon:file-text-alt[role="blue"]
:language: asciidoc
:source-language: asciidoc
:table-caption!:
:example-caption!:
:figure-caption!:
@@ -54,6 +54,10 @@ Sarah White <https://github.com/graphitefriction[@graphitefriction]>; Dan Allen
:factory-ref: http://github.com/asciidoctor/asciidoctor-stylesheet-factory
:http-ref: http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html
:pygments-org: http://pygments.org
:pygments-gem: https://rubygems.org/gems/pygments.rb
:pygments-lang: {pygments-org}/languages/
:coderay-uri: http://coderay.rubychan.de/
:coderay-gem: https://rubygems.org/gems/coderay
:showcase-ref: http://themes.asciidoctor.org/preview/
:docbook5-ref: http://www.docbook.org/tdg5/en/html/ch01.html#introduction-whats-new
:yelp: http://live.gnome.org/Yelp
@@ -65,8 +69,8 @@ Sarah White <https://github.com/graphitefriction[@graphitefriction]>; Dan Allen
:fopub-doc-ref: https://github.com/asciidoctor/asciidoctor-fopub/blob/master/README.adoc
:backend-git: http://github.com/asciidoctor/asciidoctor-backends
:deckjs-org: http://imakewebthings.com/deck.js
:deckjs-zip: https://github.com/imakewebthings/deck.js/zipball/stable
:deckjs-git: https://github.com/imakewebthings/deck.js
:deckjs-zip: {deckjs-git}/zipball/stable
:decksplitjs-git: https://github.com/houqp/deck.split.js
:compass-ref: http://compass-style.org
:sass-ref: http://sass-lang.com
@@ -1263,10 +1267,14 @@ NOTE: Pending
include::{includedir}/hl.adoc[]
==== Pygments installation
==== Pygments
include::{includedir}/hl-pygment.adoc[]
==== CodeRay
include::{includedir}/hl-coderay.adoc[]
== Include Directive
include::{includedir}/include-directive.adoc[]
@@ -1442,6 +1450,7 @@ include::{includedir}/html-styles.adoc[]
include::{includedir}/html-manage-images.adoc[]
[[hl-css]]
=== CodeRay and Pygments stylesheets
include::{includedir}/html-code-styles.adoc[]
Binary file not shown.

0 comments on commit 65e308b

Please sign in to comment.