Skip to content

Latest commit

 

History

History
316 lines (233 loc) · 9.17 KB

asciidoctor-example.asciidoc

File metadata and controls

316 lines (233 loc) · 9.17 KB

ALAN Docs Rouge Lexers

Table of Contents

Previews of our custom Rouge lexers and themes for the ALAN Docs project, and other ALAN-related documentation.

Warning

Currently we only have the ALAN lexer, and a single theme. In the future this document we’ll also cover the other required lexers (BNF) and ALAN themes ("tutorial" and "lib").

ALAN Samples

Warning

WIP THEMES! — The CSS themes are still incomplete, I need to:

  • ❏ Adjust the old Highlight class names to those of Rouge.

  • ❏ Add/cover new syntax elements introduced by Rouge.

  • ✓ Fix some precedence issues which are preventing the custom ALAN themes to override styles from the native Rouge theme.

Basic Sample

A basic ALAN IF code sample, shown in all available theme variations.

Default Theme

link:sample.alan[role=include]

Library Theme

link:sample.alan[role=include]

Tutorial Theme

link:sample.alan[role=include]

AsciiDoc Features

Here some sample of advanced AsciiDoc features and how they’re rendered for each theme.

Callouts

Example 1. Callouts: Default Theme
Every beverage IsA object -- (1) (2)
  Is drinkable. -- (3)
End every.

  1. beverage is the new class.

  2. object is the parent class.

  3. The drinkable attribute is used by the drink verb.

Example 2. Callouts: Library Theme
Every beverage IsA object -- (1) (2)
  Is drinkable. -- (3)
End every.

  1. beverage is the new class.

  2. object is the parent class.

  3. The drinkable attribute is used by the drink verb.

Example 3. Callouts: Tutorial Theme
Every beverage IsA object -- (1) (2)
  Is drinkable. -- (3)
End every.

  1. beverage is the new class.

  2. object is the parent class.

  3. The drinkable attribute is used by the drink verb.

Code Markers

Specific code selections can be styled as if marked via a highlighter pen, using the #..# and [green]#..# notations for yellow and green, which will wrap their in content in <mark> and <span class="green">, respectively.

Warning

It looks like using subs=quotes completely breaks syntax highlighting with Rouge!

This is going to affect the ALAN Beginner’s Guide, which heavily relies on this feature; so probably we can’t use Rouge for that publication.
Highlighter Marks: Default Theme
Every beverage IsA object -- yellow marker
  Is drinkable.    -- green marker
End every.
Highlighter Marks: Library Theme
Every beverage IsA object -- yellow marker
  Is drinkable.    -- green marker
End every.
Highlighter Marks: Tutorial Theme
Every beverage IsA object -- yellow marker
  Is drinkable.    -- green marker
End every.

ALAN Syntax Details

Here we’ll have a closer look at specific syntax elements, and how they are rendered (or hidden) by the various CSS themes for ALAN code.

Strings

Here’s how strings and their delimiters, along with escapes and interpolations are rendered across themes:

Default Theme
Say "You carefully inspect $+1; it surely doesn't resemble
     any other $01 you've ever seen, $!1 features are unique.
     $p$iYou tell Bob ""This $1 might be what we were looking for""."
Library Theme
Say "You carefully inspect $+1; it surely doesn't resemble
     any other $01 you've ever seen, $!1 features are unique.
     $p$iYou tell Bob ""This $1 might be what we were looking for""."
Tutorial Theme
Say "You carefully inspect $+1; it surely doesn't resemble
     any other $01 you've ever seen, $!1 features are unique.
     $p$iYou tell Bob ""This $1 might be what we were looking for""."

Escapes and Interpolations

ALAN’s “special characters combinations” are captured as either escape sequences or interpolations by our Rouge lexer.

We capture as escape sequences those special characters groups which are substituted by some fixed literal character (including ""):

String Escapes: Default Theme
"$$ $_ $i $n $p $t """
String Escapes: Library Theme
"$$ $_ $i $n $p $t """
String Escapes: Tutorial Theme
"$$ $_ $i $n $p $t """

We capture as interpolations those special characters groups which are substituted by some dynamic game-reference:

String Interpolations: Default Theme
"$1 $+2 $03 $-1 $!2 $a $l $o $v"
String Interpolations: Library Theme
"$1 $+2 $03 $-1 $!2 $a $l $o $v"
String Interpolations: Tutorial Theme
"$1 $+2 $03 $-1 $!2 $a $l $o $v"
Note

The way these special characters are grouped in the ALAN Manual differs from the way they are treated by our lexer.

The official documentation doesn’t classify them as either escapes or interpolations, and they are presented in two separate groups based on whether they refer to VERB parameters or not.

Our approach here is different, for we’re trying to classify them as tokens, according to their nature. The closest token types that I could come up with (and which are supported by Rouge) are escape sequences and interpolations, which seem to represent their behaviour fairly accurately.

File Names as Quoted IDs

ALAN uses quoted IDs (instead of strings) to hand file names following import, play and show. The Rouge ALAN lexer will capture as single-quoted strings quoted IDs representing files names, and capture their enclosing ' as a single-quote string delimiter.

Default Theme
IMPORT 'StdLib/library.i'.
PLAY 'mmedia\music.aiff'.
SHOW 'mmedia\picture.jpeg'.
Library Theme
IMPORT 'StdLib/library.i'.
PLAY 'mmedia\music.aiff'.
SHOW 'mmedia\picture.jpeg'.
Tutorial Theme
IMPORT 'StdLib/library.i'.
PLAY 'mmedia\music.aiff'.
SHOW 'mmedia\picture.jpeg'.

Other Syntaxes

Code blocks for languages not covered by our custom CSS will fallback to use the native Rouge theme defined via the :rouge-style: attribute. Example, using the thankful_eyes theme:

link:custom-rouge-adapter.rb[role=include]
Note
 If no theme is specified via :rouge-style:, Asciidoctor will default to the github theme.

Asciidoctor will convert the native Rouge theme to CSS and inject it in its default CSS stylesheet, which won’t interfere with out custom styles and themes.

This is quite convenient, for it ensures that code examples from other languages are also highlighted (i.e. if Rouge has a lexer for that language), and authors of a document are free to choose their fallback theme of choice.

The names of the currently available native Rouge themes are:

base16

Default base16 theme.
bw

A port of Pygment’s “Black and White” theme.
colorful

A port of Pygment’s “Colorful” theme.
github

“GitHub” theme.
gruvbox

Based on the “gruvbox” theme.
igorpro

“Igor Pro”.
magritte

“Magritte”.
molokai

A “Monokai” variation.
monokai.sublime

“Monokai Sublime”, a Monokai variation inspired by Sublime Text.
monokai

“Monokai” classic.
pastie

A port of Pygment’s “Pastie” theme.
thankful_eyes

Thankful Eyes.
tulip

Tulip.