Author: Tristano Ajmone

# Original HighlightTreeprocessor Example

Tristano Ajmone
tajmone@gmail.com
version 1, 2019-03-25

A demonstration of the original HighlightTreeprocessor extension published on the Asciidoctor Extensions Lab project.

## Highlighting Previews

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

Associated files:

- `highlight-treeprocessor.rb`

### Example 1

    ; ==============================================================================
    ;                   PureBasic 5.62 - Syntax Highlighting Test
    ; ==============================================================================
    ; by Tristano Ajmone (2018/10/04), public domain: http://unlicense.org

    Declare.i CountdownDialog(text.s)

    Macro IsEven(num)
      (num & 1 = 0)
    EndMacro

    For i=5 To 1 Step -1
      If isEven(i) : Debug Str(i) +" is even." : EndIf
      TEXT$ = "Iteration number: " + Str(i) + ~"\n\nDo you wish to continue?"
      If CountdownDialog(TEXT$) : Break : EndIf
    Next

    MyVar = %1011 << 1
    EnableASM
    INC MyVar ; Mix ASM keywords with PureBasic variable
    DisableASM
    Debug "MyVar: "+Str(MyVar)

    Procedure.i CountdownDialog(text.s)
      UserChoice = MessageRequester("Countdown Dialog", text, #PB_MessageRequester_YesNo |
                                                              #PB_MessageRequester_Info)
      If UserChoice = #PB_MessageRequester_No
        CompilerIf #PB_Compiler_Processor = #PB_Processor_x64
          !mov rax,1
        CompilerElse
          !mov eax,1
        CompilerEndIf
      Else
        ProcedureReturn 0
      EndIf
      ProcedureReturn ; RAX/EAX will be the implicit return value
    EndProcedure

### Example 2: Line Numbers

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

     1 --==============================================================================
     2 -- "Chez Alan" by Tristano Ajmone, 2018 || Public domain: http://unlicense.org
     3 --==============================================================================
     4 Import 'library.i'. --> ALAN Standard Library v2.1
     5
     6 The my_game IsA definition_block
     7   Has title    "Chez Alan".
     8   Has subtitle "A small demo adventure".
     9   Has author   "Tristano Ajmone".
    10   Has year     2018.
    11   Has version  "1".
    12 End The.
    13
    14 The 'IF Plaza' IsA location
    15   Exit north to ChezAlan.
    16   Description "North lies ""Chez Alan"", the renown French brasserie."
    17 End The 'IF Plaza'.
    18
    19 The ChezAlan IsA room.
    20   Name 'Chez Alan Brasserie'.
    21   Description
    22     "Today Chez Alan seems busier then ever."
    23   Entered
    24     """Welcome back Sir!"" the maitre greets you.
    25     $nHe has a strong French accent."
    26 End The ChezAlan.
    27
    28 The Pierre IsA male At ChezAlan.
    29   Name Pierre.
    30   Name 'Alan''s' brother.
    31   Is named.
    32   Has ex "Pierre is Alan's brother.".
    33 End The Pierre.
    34
    35 Start At 'IF Plaza'.
    36 Describe banner.

## Usage Instructions

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

    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:

    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:

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.

| 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):

    <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):

    <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`).

| 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

    <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

     1 require 'sinatra'
     2
     3 get '/hi' do
     4   "Hello World!"
     5 end

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