rename source-highlighters module to syntax-highlighting

6 files changed, 412 insertions, 0 deletions

diff --git a/docs/modules/syntax-highlighting/nav.adoc b/docs/modules/syntax-highlighting/nav.adoc
new file mode 100644
index 00000000..7464bc7e
--- /dev/null
+++ b/docs/modules/syntax-highlighting/nav.adoc
@@ -0,0 +1,5 @@
+* xref:index.adoc[]
+** xref:highlightjs.adoc[]
+** xref:rouge.adoc[]
+** xref:coderay.adoc[]
+** xref:pygments.adoc[]
diff --git a/docs/modules/syntax-highlighting/pages/coderay.adoc b/docs/modules/syntax-highlighting/pages/coderay.adoc
new file mode 100644
index 00000000..c7b035a9
--- /dev/null
+++ b/docs/modules/syntax-highlighting/pages/coderay.adoc
@@ -0,0 +1,107 @@
+= CodeRay
+:url-coderay: http://coderay.rubychan.de/
+:url-coderay-gem: https://rubygems.org/gems/coderay
+
+{url-coderay}[CodeRay^] is an encoding-aware, syntax highlighter that supports the languages listed below.
+
+[%autowidth,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
+|
+|===
+
+== Install CodeRay
+
+To use CodeRay with Asciidoctor, you need the {url-coderay-gem}[coderay RubyGem^].
+You can use one of the following methods to install CodeRay.
+
+Install using gem (all systems)::
++
+ $ gem install coderay
+
+Install using apt-get (Debian-based systems)::
++
+ $ sudo apt-get install coderay
+
+Install using dnf (Fedora-based systems)::
++
+ $ sudo dnf install rubygem-coderay
+
+== Activate CodeRay
+
+Once you've installed the RubyGem, assign the `coderay` value to the `source-highlighter` attribute in the document header to activate it.
+
+[source]
+----
+:source-highlighter: coderay
+----
+
+== CodeRay attributes
+
+You can further customize the source block output with additional CodeRay attributes.
+
+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`.
+If line wrapping is enabled on preformatted blocks (i.e., `prewrap`), and you want to use line numbering on source blocks, you must set the value of this attribute to `inline` in order for the numbers to line up properly with their target lines.
+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 xref:html-backend:source-highlighting-stylesheets.adoc#coderay[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.
+////
diff --git a/docs/modules/syntax-highlighting/pages/highlightjs.adoc b/docs/modules/syntax-highlighting/pages/highlightjs.adoc
new file mode 100644
index 00000000..17372031
--- /dev/null
+++ b/docs/modules/syntax-highlighting/pages/highlightjs.adoc
@@ -0,0 +1,42 @@
+= Highlight.js
+:url-highlightjs: https://highlightjs.org/
+:url-highlightjs-lang: https://highlightjs.org/download/
+:url-highlightjs-cdn: https://cdnjs.com/libraries/highlight.js
+
+{url-highlightjs}[Highlight.js^] is a popular client-side syntax highlighter that supports a broad range of {url-highlightjs-lang}[languages^].
+
+== Activate highlight.js
+
+To activate highlight.js, add the following attribute entry to the header of your AsciiDoc file:
+
+[source]
+----
+:source-highlighter: highlight.js
+----
+
+By default, Asciidoctor will link to the highlight.js library and stylesheet hosted on {url-highlightjs-cdn}[cdnjs^].
+The version of the highlight.js library Asciidoctor loads from the CDN only includes support for languages in the common language bundle (apache, bash, coffeescript, cpp, cs, css, diff, http, ini, java, javascript, json, makefile, markdown, nginx, objectivec, perl, php, properties, python, ruby, shell, sql, xml, and yaml).
+
+== Load support for additional languages
+
+To load additional languages supported by highlight.js, list them in the value of the `highlightjs-languages` document attribute (separated by commas):
+
+[source]
+----
+:source-highlighter: highlight.js
+:highlightjs-languages: rust, swift
+----
+
+== Using a custom highlight.js library
+
+If you'd rather use a personal copy of highlight.js instead of the one hosted on the CDN, follow these steps:
+
+. Create your custom bundle on the {url-highlightjs-lang}[download page^].
+. Download and unpack the zip into a folder called [.path]_highlight_ adjacent to your AsciiDoc file (or in the output directory, if different)
+. Rename [.path]_highlight/highlight.pack.js_ to [.path]_highlight/highlight.min.js_
+. Rename [.path]_highlight/styles/github.css_ to [.path]_highlight/styles/github.min.css_
+** Replace `github` with the name of the `highlightjs-theme` you are using, if different.
+. Add the attribute entry `:highlightjsdir: highlight` to the header of your AsciiDoc file.
+** Alternatively, you can pass the `-a highlightjsdir=highlight` flag when invoking the Asciidoctor CLI.
+
+The output file will use your personal copy of the highlight.js library and stylesheet instead of the one hosted on cdnjs.
diff --git a/docs/modules/syntax-highlighting/pages/index.adoc b/docs/modules/syntax-highlighting/pages/index.adoc
new file mode 100644
index 00000000..bc3d4222
--- /dev/null
+++ b/docs/modules/syntax-highlighting/pages/index.adoc
@@ -0,0 +1,32 @@
+= Syntax Highlighting
+
+[%autowidth]
+|===
+| |Syntax Highlighter |Supported Versions |Converters
+
+|Client-side highlighting for source code blocks
+
+|Highlight.js
+|9.18.3
+|HTML
+
+.3+|Server-side highlighting for source code blocks
+
+|CodeRay
+|1.1.2
+|HTML
+
+|Pygments
+|2.2.0
+|HTML
+
+|Rouge
+|3.1.1
+|HTML
+|===
+
+////
+|Inline, admonition or callout font-based icons
+|Font Awesome
+|4.7
+////
diff --git a/docs/modules/syntax-highlighting/pages/pygments.adoc b/docs/modules/syntax-highlighting/pages/pygments.adoc
new file mode 100644
index 00000000..a049b690
--- /dev/null
+++ b/docs/modules/syntax-highlighting/pages/pygments.adoc
@@ -0,0 +1,156 @@
+= Pygments
+:url-pygments: https://pygments.org
+:url-pygments-lang: https://pygments.org/languages/
+:url-python: https://www.python.org
+:url-pygments-gem: https://rubygems.org/gems/pygments.rb
+
+{url-pygments}[Pygments^] is a popular syntax highlighter that supports a broad range of {url-pygments-lang}[programming and template languages^].
+
+== Install Pygments
+
+In order to use Pygments with Asciidoctor, you need {url-python}[Python 2^] and the {url-pygments-gem}[pygments.rb gem^].
+The pygments.rb gem manages calls to Pygments, which is an external program that runs using Python.
+
+TIP: You do not need to install Pygments itself.
+It comes bundled with the pygments.rb gem.
+
+IMPORTANT: You must have Python 2 installed to use pygments.rb.
+Python 3 is not compatible with the pygments.rb gem.
+Check that you have a `python2` (Linux), `python` (macOS), or `py -2` (Windows) executable on your PATH.
+(On macOS, verify that the `python` executable uses Python 2 by running `python -V`).
+
+.Installing Python and the pygments.rb gem via the CLI (cross platform)
+[source,console]
+....
+$ "`\which apt-get || \which dnf || \which yum || \which brew`" install python # <.>
+$ gem install pygments.rb # <.>
+....
+<.> Install Python using your package manager
+<.> Install the pygments.rb gem
+
+== Activate Pygments
+
+Once you've installed these libraries, assign `pygments` to the `source-highlighter` attribute in your document's header.
+
+[source]
+----
+:source-highlighter: pygments
+----
+
+== Pygments attributes
+
+You can further customize the source block output with additional Pygments attributes.
+
+pygments-style::
+Sets the name of the color theme Pygments uses.
+To see the list of available style names, see <<listing-pygments-style-names>>.
+Default: `pastie`.
+
+pygments-css::
+Controls what method is used for applying CSS to the tokens.
+Can be `class` (CSS classes) or `style` (inline styles).
+See the xref:html-backend:source-highlighting-stylesheets.adoc#pygments[Pygments stylesheet section] to learn more about how the value `class` is handled.
+Default: `class`.
+
+pygments-linenums-mode::
+Controls how line numbers are arranged when line numbers are enabled on the source block.
+Can be `table` or `inline`.
+If line wrapping is enabled on preformatted blocks (i.e., `prewrap`), and you want to use line numbering on source blocks, you must set the value of this attribute to `inline` in order for the numbers to line up properly with their target lines.
+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'
+}
+----
+....
+
+////
+.Result: 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.]
+====
+////
+
+[#listing-pygments-style-names]
+=== Available Pygments style names
+
+To list the available Pygments styles, run the following command in a terminal:
+
+ $ $(dirname $(gem which pygments.rb))/../vendor/pygments-main/pygmentize -L styles
+
+The pygments.rb gem uses a bundled version of Pygments (often ahead of the latest release).
+This command ensures that you are invoking the `pygmentize` command from the Pygments used by that gem.
+
+== Pygments timeout
+
+Since Pygments is an external program, the call to that command is managed by a timeout to safe-guard against a hanging process.
+By default, this timeout is 8 seconds.
+If you discover that the call is failing to complete within this timeout period, you can increase the timeout (in seconds) by setting the `MENTOS_TIMEOUT` environment variable.
+
+ export MENTOS_TIMEOUT=30
+
+Now the call to Pygments will be allocated up to 30 seconds to complete.
+
+== Using a custom Pygments installation
+
+If you already have Pygments installed on your system, you want to use your own fork, or you want to customize how Pygments is configured, you can get Asciidoctor to use a custom version of Pygments instead of the one bundled with the pygments.rb gem.
+
+First, install your own version of Pygments.
+You can do this, for instance, by cloning the upstream Pygments repository:
+
+ $ hg clone https://bitbucket.org/birkenfeld/pygments-main pygments
+
+Find the directory that contains the file [.path]_pygmentize_ or the [.path]_Makefile_.
+That's your Pygments installation path.
+Make note of it.
+
+Next, create a script to run _before_ invoking Asciidoctor for the first time.
+Let's call it [.path]_pygments_init.rb_.
+Populate the script with the following content:
+
+.pygments_init.rb
+[source,ruby]
+----
+require 'pygments'
+
+# use a custom Pygments installation (directory that contains pygmentize)
+Pygments.start '/path/to/pygments'
+
+# example of registering a missing or additional lexer
+#Pygments::Lexer.create name: 'Turtle', aliases: ['turtle'],
+#    filenames: ['*.ttl'], mimetypes: ['text/turtle', 'application/x-turtle']
+----
+
+TIP: You could enhance this script to read the Pygments installation path from an environment variable (or configuration file).
+
+Now just require this script before your invoke Asciidoctor the first time.
+When using the `asciidoctor` command, pass the script using the `-r` flag:
+
+ $ asciidoctor -r ./pygments_init.rb document.adoc
+
+When using the Asciidoctor API, require the script using `require` or `require_relative`:
+
+[source,ruby]
+----
+require 'asciidoctor'
+require_relative './pygments_init.rb'
+
+Asciidoctor.convert_file 'document.adoc', safe: :safe
+----
+
+Now Asciidoctor is using your custom installation of Pygments instead of the one bundled with the pygments.rb gem.
diff --git a/docs/modules/syntax-highlighting/pages/rouge.adoc b/docs/modules/syntax-highlighting/pages/rouge.adoc
new file mode 100644
index 00000000..b6022864
--- /dev/null
+++ b/docs/modules/syntax-highlighting/pages/rouge.adoc
@@ -0,0 +1,70 @@
+= Rouge
+:url-rouge: http://rouge.jneen.net
+:url-rouge-gem: https://rubygems.org/gems/rouge
+:url-rouge-repo: https://github.com/rouge-ruby/rouge/tree/master/lib/rouge/themes
+
+{url-rouge}[Rouge^] is an extendable code highlighter written in Ruby that supports a vast array of languages.
+
+== Install Rouge
+
+To use Rouge with Asciidoctor, you need the {url-rouge-gem}[rouge RubyGem^].
+You can use one of the following methods to install Rouge.
+
+Install using `gem` (all systems)::
++
+ $ gem install rouge
+
+Install using `apt-get` (Debian-based systems)::
++
+ $ sudo apt-get install rouge
+
+Install using `dnf` (Fedora-based systems)::
++
+ $ sudo dnf install rubygem-rouge
+
+== Assign rouge to source-highlighter
+
+Once you've installed the RubyGem, assign the `rouge` value to the `source-highlighter` attribute in the document header to activate it.
+
+[source]
+----
+:source-highlighter: rouge
+----
+
+== Rouge attributes
+
+You can further customize the source block output with additional Rouge attributes.
+
+rouge-css::
+Controls what method is used for applying CSS to the tokens.
+Can be `class` or `style`.
+Default: `class`.
+
+[.line-through]#rouge-linenums-mode# (not currently implemented)::
+Controls how line numbers are laid out.
+Can be `table` or `inline`.
+If line wrapping is enabled on preformatted blocks (i.e., `prewrap`), and you want to use line numbering on source blocks, you must set the value of this attribute to `inline` in order for the numbers to line up properly with their target lines.
+Default: `table`.
+
+rouge-style::
+Controls the color theme used to for highlighting.
+You can find the list of themes in the {url-rouge-repo}[Rouge code repository^].
+
+.Customizing a source block with Rouge line numbers
+[source]
+....
+:source-highlighter: rouge
+
+[source,ruby,linenums]
+----
+ORDERED_LIST_KEYWORDS = {
+  'loweralpha' => 'a',
+  'lowerroman' => 'i',
+  'upperalpha' => 'A',
+  'upperroman' => 'I'
+   #'lowergreek' => 'a'
+   #'arabic'     => '1'
+   #'decimal'    => '1'
+}
+----
+....