= Original HighlightTreeprocessor Example
Tristano Ajmone <tajmone@gmail.com>
v1, 2019-03-25
:toclevels: 5
:toc: left
:experimental: true
:icons: font
:linkattrs: true
:reproducible: true
:sectanchors:
// ===================
// Highlight Settings:
// ===================
:source-highlighter: highlight
:highlight-style: kellys

A demonstration of the original *HighlightTreeprocessor* extension published on the
link:https://github.com/asciidoctor/asciidoctor-extensions-lab[Asciidoctor Extensions Lab]
project.


== Highlighting Previews

A couple of examples of how the rendered code looks like.

Associated files:

* link:./highlight-treeprocessor.rb[`highlight-treeprocessor.rb`]



=== Example 1


[source,purebasic]
------------------
include::../langs-examples/ex-src/PureBasic.pb[]
------------------

=== Example 2: Line Numbers

Now we add the `linenum` option to enable line-numbering:

[source,alan,linenum]
------------------
include::../langs-examples/ex-src/alan.alan[]
------------------




== Usage Instructions


To enable the *HighlightTreeprocessor* extension you must invoke Asciidoctor with the `-r` (`--require`) option:

[source,bash]
------------------------------------------------------------------
asciidoctor -r ./highlight-treeprocessor.rb your_document.asciidoc
------------------------------------------------------------------

To enable using Highlight, you need to set the `source-highlighter` attribute to `highlight`.
You may do so via the command line, using the `-a` (`--attribute`) option:

[source,bash]
-----------------------------------
asciidoctor \
  -r ./highlight-treeprocessor.rb \
  -a source-highlighter=highlight \
  your_document.asciidoc
-----------------------------------

or you can declare the attribute inside the document header:

..............................
:source-highlighter: highlight
..............................


=== Highlight Options



==== Theme and Style

The original extension exposes two attributes to set the Highlight theme and to control the CSS styling format:

[cols="4*<d",options="header"]
|==========
| attribute name
| allowed values
| default value
| Highlight option

| `highlight-style`
| any theme name
| `edit-eclipse`
| `--style=<value>`

| `highlight-css`
| `class`/`style`
| `class`
| _none_/`--inline-css`
|==========

The `highlight-style` attribute allows you to choose any Highlight theme by setting its value to the theme's filename (without the extension).
The selected theme must be inside Highlight `/themes/` folder.

NOTE: The *HighlightTreeprocessor* extension only allows you to pick a single theme per document.

By default, Asciidoctor will set `highlight-css` to `class`, so that Highlight will use class names to style the various syntax elements (which is also Highlight default behavior):

[source,html]
--------------------------------------------------------------------------------
<span class="hl kwa">require</span>
--------------------------------------------------------------------------------

whereas setting `highlight-css` to `style` will inline the CSS definitions into the tags, instead of using classes (i.e. Highlight is invoked with the `--inline-css` option):

[source,html]
--------------------------------------------------------------------------------
<span style="color:#62acce; font-weight:bold">require</span>
--------------------------------------------------------------------------------

Obviously, the latter solution is more verbose, so you're better off not setting the `highlight-css` attribute at all, and just stick to the extension default value (`class`).


WARNING: The `style` option fails to style the background color (i.e. Highlight `canvas`), probably due to the extension being very old and Highlight having changed tag/classes in the HTML output.

When `highlight-css` is set to `class`, the extension will get the CSS stylesheet of the `highlight-style` theme by invoking Highlight with the `-c stdout --print-style -s` option, and injects it at the end of the output HTML document:

.HTML Example
[source,css]
--------------------------------------------------------------------------------
<style>
/* Style definition file generated by highlight 3.49, http://www.andre-simon.de/ */
/* highlight theme: vim kellys */
body.hl { background-color:#2a2b2f; }
.listingblock pre.highlight { background-color:#2a2b2f; }
pre.highlight>code { color: #e1e0e5; }
.hl.num { color:#dabc7f; }
.hl.esc { color:#9ab2c8; }
.hl.str { color:#dabc7f; }
.hl.pps { color:#dabc7f; }
.hl.slc { color:#67686b; }
.hl.com { color:#67686b; }
.hl.ppc { color:#77cf63; }
.hl.opt { color:#e1e0e5; }
.hl.ipl { color:#c75e75; }
.hl.lin { color:#a3a362; }
.hl.kwa { color:#62acce; font-weight:bold; }
.hl.kwb { color:#e6ac32; }
.hl.kwc { color:#cf8563; }
.hl.kwd { color:#bb63cf; }
</style>
</body>
</html>
--------------------------------------------------------------------------------



==== Line Numbering

Furthermore, you can enable line-numbering via the `linenums` option to the source block style of a listing block:

.AsciiDoc Example
.....................
[source,ruby,linenum]
---------------------
require 'sinatra'

get '/hi' do
  "Hello World!"
end
---------------------
.....................


.Result Preview

[source,ruby,linenum]
---------------------
require 'sinatra'

get '/hi' do
  "Hello World!"
end
---------------------

When `linenums` is used, Highlight is invoked with the `-l -j 2` options.



// EOF //