current commit
191019.1 · Typo fixes
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="Asciidoctor 2.0.6">
<meta name="author" content="Tristano Ajmone">
<title>Highlight Support for Asciidoctor</title>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700">
<style>
/* Asciidoctor default stylesheet | MIT License | https://asciidoctor.org */
/* Uncomment @import statement when using as custom stylesheet */
/*@import "https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700";*/
article,aside,details,figcaption,figure,footer,header,hgroup,main,nav,section{display:block}
audio,canvas,video{display:inline-block}
audio:not([controls]){display:none;height:0}
script{display:none!important}
html{font-family:sans-serif;-ms-text-size-adjust:100%;-webkit-text-size-adjust:100%}
a{background:none}
a:focus{outline:thin dotted}
a:active,a:hover{outline:0}
h1{font-size:2em;margin:.67em 0}
abbr[title]{border-bottom:1px dotted}
b,strong{font-weight:bold}
dfn{font-style:italic}
hr{-moz-box-sizing:content-box;box-sizing:content-box;height:0}
mark{background:#ff0;color:#000}
code,kbd,pre,samp{font-family:monospace;font-size:1em}
pre{white-space:pre-wrap}
q{quotes:"\201C" "\201D" "\2018" "\2019"}
small{font-size:80%}
sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}
sup{top:-.5em}
sub{bottom:-.25em}
img{border:0}
svg:not(:root){overflow:hidden}
figure{margin:0}
fieldset{border:1px solid silver;margin:0 2px;padding:.35em .625em .75em}
legend{border:0;padding:0}
button,input,select,textarea{font-family:inherit;font-size:100%;margin:0}
button,input{line-height:normal}
button,select{text-transform:none}
button,html input[type="button"],input[type="reset"],input[type="submit"]{-webkit-appearance:button;cursor:pointer}
button[disabled],html input[disabled]{cursor:default}
input[type="checkbox"],input[type="radio"]{box-sizing:border-box;padding:0}
button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0}
textarea{overflow:auto;vertical-align:top}
table{border-collapse:collapse;border-spacing:0}
*,*::before,*::after{-moz-box-sizing:border-box;-webkit-box-sizing:border-box;box-sizing:border-box}
html,body{font-size:100%}
body{background:#fff;color:rgba(0,0,0,.8);padding:0;margin:0;font-family:"Noto Serif","DejaVu Serif",serif;font-weight:400;font-style:normal;line-height:1;position:relative;cursor:auto;tab-size:4;-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased}
a:hover{cursor:pointer}
img,object,embed{max-width:100%;height:auto}
object,embed{height:100%}
img{-ms-interpolation-mode:bicubic}
.left{float:left!important}
.right{float:right!important}
.text-left{text-align:left!important}
.text-right{text-align:right!important}
.text-center{text-align:center!important}
.text-justify{text-align:justify!important}
.hide{display:none}
img,object,svg{display:inline-block;vertical-align:middle}
textarea{height:auto;min-height:50px}
select{width:100%}
.center{margin-left:auto;margin-right:auto}
.stretch{width:100%}
.subheader,.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{line-height:1.45;color:#7a2518;font-weight:400;margin-top:0;margin-bottom:.25em}
div,dl,dt,dd,ul,ol,li,h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6,pre,form,p,blockquote,th,td{margin:0;padding:0;direction:ltr}
a{color:#2156a5;text-decoration:underline;line-height:inherit}
a:hover,a:focus{color:#1d4b8f}
a img{border:0}
p{font-family:inherit;font-weight:400;font-size:1em;line-height:1.6;margin-bottom:1.25em;text-rendering:optimizeLegibility}
p aside{font-size:.875em;line-height:1.35;font-style:italic}
h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{font-family:"Open Sans","DejaVu Sans",sans-serif;font-weight:300;font-style:normal;color:#ba3925;text-rendering:optimizeLegibility;margin-top:1em;margin-bottom:.5em;line-height:1.0125em}
h1 small,h2 small,h3 small,#toctitle small,.sidebarblock>.content>.title small,h4 small,h5 small,h6 small{font-size:60%;color:#e99b8f;line-height:0}
h1{font-size:2.125em}
h2{font-size:1.6875em}
h3,#toctitle,.sidebarblock>.content>.title{font-size:1.375em}
h4,h5{font-size:1.125em}
h6{font-size:1em}
hr{border:solid #dddddf;border-width:1px 0 0;clear:both;margin:1.25em 0 1.1875em;height:0}
em,i{font-style:italic;line-height:inherit}
strong,b{font-weight:bold;line-height:inherit}
small{font-size:60%;line-height:inherit}
code{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;color:rgba(0,0,0,.9)}
ul,ol,dl{font-size:1em;line-height:1.6;margin-bottom:1.25em;list-style-position:outside;font-family:inherit}
ul,ol{margin-left:1.5em}
ul li ul,ul li ol{margin-left:1.25em;margin-bottom:0;font-size:1em}
ul.square li ul,ul.circle li ul,ul.disc li ul{list-style:inherit}
ul.square{list-style-type:square}
ul.circle{list-style-type:circle}
ul.disc{list-style-type:disc}
ol li ul,ol li ol{margin-left:1.25em;margin-bottom:0}
dl dt{margin-bottom:.3125em;font-weight:bold}
dl dd{margin-bottom:1.25em}
abbr,acronym{text-transform:uppercase;font-size:90%;color:rgba(0,0,0,.8);border-bottom:1px dotted #ddd;cursor:help}
abbr{text-transform:none}
blockquote{margin:0 0 1.25em;padding:.5625em 1.25em 0 1.1875em;border-left:1px solid #ddd}
blockquote cite{display:block;font-size:.9375em;color:rgba(0,0,0,.6)}
blockquote cite::before{content:"\2014 \0020"}
blockquote cite a,blockquote cite a:visited{color:rgba(0,0,0,.6)}
blockquote,blockquote p{line-height:1.6;color:rgba(0,0,0,.85)}
@media screen and (min-width:768px){h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2}
h1{font-size:2.75em}
h2{font-size:2.3125em}
h3,#toctitle,.sidebarblock>.content>.title{font-size:1.6875em}
h4{font-size:1.4375em}}
table{background:#fff;margin-bottom:1.25em;border:solid 1px #dedede}
table thead,table tfoot{background:#f7f8f7}
table thead tr th,table thead tr td,table tfoot tr th,table tfoot tr td{padding:.5em .625em .625em;font-size:inherit;color:rgba(0,0,0,.8);text-align:left}
table tr th,table tr td{padding:.5625em .625em;font-size:inherit;color:rgba(0,0,0,.8)}
table tr.even,table tr.alt{background:#f8f8f7}
table thead tr th,table tfoot tr th,table tbody tr td,table tr td,table tfoot tr td{display:table-cell;line-height:1.6}
h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2;word-spacing:-.05em}
h1 strong,h2 strong,h3 strong,#toctitle strong,.sidebarblock>.content>.title strong,h4 strong,h5 strong,h6 strong{font-weight:400}
.clearfix::before,.clearfix::after,.float-group::before,.float-group::after{content:" ";display:table}
.clearfix::after,.float-group::after{clear:both}
:not(pre):not([class^=L])>code{font-size:.9375em;font-style:normal!important;letter-spacing:0;padding:.1em .5ex;word-spacing:-.15em;background:#f7f7f8;-webkit-border-radius:4px;border-radius:4px;line-height:1.45;text-rendering:optimizeSpeed;word-wrap:break-word}
:not(pre)>code.nobreak{word-wrap:normal}
:not(pre)>code.nowrap{white-space:nowrap}
pre{color:rgba(0,0,0,.9);font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;line-height:1.45;text-rendering:optimizeSpeed}
pre code,pre pre{color:inherit;font-size:inherit;line-height:inherit}
pre>code{display:block}
pre.nowrap,pre.nowrap pre{white-space:pre;word-wrap:normal}
em em{font-style:normal}
strong strong{font-weight:400}
.keyseq{color:rgba(51,51,51,.8)}
kbd{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;display:inline-block;color:rgba(0,0,0,.8);font-size:.65em;line-height:1.45;background:#f7f7f7;border:1px solid #ccc;-webkit-border-radius:3px;border-radius:3px;-webkit-box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em white inset;box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em #fff inset;margin:0 .15em;padding:.2em .5em;vertical-align:middle;position:relative;top:-.1em;white-space:nowrap}
.keyseq kbd:first-child{margin-left:0}
.keyseq kbd:last-child{margin-right:0}
.menuseq,.menuref{color:#000}
.menuseq b:not(.caret),.menuref{font-weight:inherit}
.menuseq{word-spacing:-.02em}
.menuseq b.caret{font-size:1.25em;line-height:.8}
.menuseq i.caret{font-weight:bold;text-align:center;width:.45em}
b.button::before,b.button::after{position:relative;top:-1px;font-weight:400}
b.button::before{content:"[";padding:0 3px 0 2px}
b.button::after{content:"]";padding:0 2px 0 3px}
p a>code:hover{color:rgba(0,0,0,.9)}
#header,#content,#footnotes,#footer{width:100%;margin-left:auto;margin-right:auto;margin-top:0;margin-bottom:0;max-width:62.5em;*zoom:1;position:relative;padding-left:.9375em;padding-right:.9375em}
#header::before,#header::after,#content::before,#content::after,#footnotes::before,#footnotes::after,#footer::before,#footer::after{content:" ";display:table}
#header::after,#content::after,#footnotes::after,#footer::after{clear:both}
#content{margin-top:1.25em}
#content::before{content:none}
#header>h1:first-child{color:rgba(0,0,0,.85);margin-top:2.25rem;margin-bottom:0}
#header>h1:first-child+#toc{margin-top:8px;border-top:1px solid #dddddf}
#header>h1:only-child,body.toc2 #header>h1:nth-last-child(2){border-bottom:1px solid #dddddf;padding-bottom:8px}
#header .details{border-bottom:1px solid #dddddf;line-height:1.45;padding-top:.25em;padding-bottom:.25em;padding-left:.25em;color:rgba(0,0,0,.6);display:-ms-flexbox;display:-webkit-flex;display:flex;-ms-flex-flow:row wrap;-webkit-flex-flow:row wrap;flex-flow:row wrap}
#header .details span:first-child{margin-left:-.125em}
#header .details span.email a{color:rgba(0,0,0,.85)}
#header .details br{display:none}
#header .details br+span::before{content:"\00a0\2013\00a0"}
#header .details br+span.author::before{content:"\00a0\22c5\00a0";color:rgba(0,0,0,.85)}
#header .details br+span#revremark::before{content:"\00a0|\00a0"}
#header #revnumber{text-transform:capitalize}
#header #revnumber::after{content:"\00a0"}
#content>h1:first-child:not([class]){color:rgba(0,0,0,.85);border-bottom:1px solid #dddddf;padding-bottom:8px;margin-top:0;padding-top:1rem;margin-bottom:1.25rem}
#toc{border-bottom:1px solid #e7e7e9;padding-bottom:.5em}
#toc>ul{margin-left:.125em}
#toc ul.sectlevel0>li>a{font-style:italic}
#toc ul.sectlevel0 ul.sectlevel1{margin:.5em 0}
#toc ul{font-family:"Open Sans","DejaVu Sans",sans-serif;list-style-type:none}
#toc li{line-height:1.3334;margin-top:.3334em}
#toc a{text-decoration:none}
#toc a:active{text-decoration:underline}
#toctitle{color:#7a2518;font-size:1.2em}
@media screen and (min-width:768px){#toctitle{font-size:1.375em}
body.toc2{padding-left:15em;padding-right:0}
#toc.toc2{margin-top:0!important;background:#f8f8f7;position:fixed;width:15em;left:0;top:0;border-right:1px solid #e7e7e9;border-top-width:0!important;border-bottom-width:0!important;z-index:1000;padding:1.25em 1em;height:100%;overflow:auto}
#toc.toc2 #toctitle{margin-top:0;margin-bottom:.8rem;font-size:1.2em}
#toc.toc2>ul{font-size:.9em;margin-bottom:0}
#toc.toc2 ul ul{margin-left:0;padding-left:1em}
#toc.toc2 ul.sectlevel0 ul.sectlevel1{padding-left:0;margin-top:.5em;margin-bottom:.5em}
body.toc2.toc-right{padding-left:0;padding-right:15em}
body.toc2.toc-right #toc.toc2{border-right-width:0;border-left:1px solid #e7e7e9;left:auto;right:0}}
@media screen and (min-width:1280px){body.toc2{padding-left:20em;padding-right:0}
#toc.toc2{width:20em}
#toc.toc2 #toctitle{font-size:1.375em}
#toc.toc2>ul{font-size:.95em}
#toc.toc2 ul ul{padding-left:1.25em}
body.toc2.toc-right{padding-left:0;padding-right:20em}}
#content #toc{border-style:solid;border-width:1px;border-color:#e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;-webkit-border-radius:4px;border-radius:4px}
#content #toc>:first-child{margin-top:0}
#content #toc>:last-child{margin-bottom:0}
#footer{max-width:100%;background:rgba(0,0,0,.8);padding:1.25em}
#footer-text{color:rgba(255,255,255,.8);line-height:1.44}
#content{margin-bottom:.625em}
.sect1{padding-bottom:.625em}
@media screen and (min-width:768px){#content{margin-bottom:1.25em}
.sect1{padding-bottom:1.25em}}
.sect1:last-child{padding-bottom:0}
.sect1+.sect1{border-top:1px solid #e7e7e9}
#content h1>a.anchor,h2>a.anchor,h3>a.anchor,#toctitle>a.anchor,.sidebarblock>.content>.title>a.anchor,h4>a.anchor,h5>a.anchor,h6>a.anchor{position:absolute;z-index:1001;width:1.5ex;margin-left:-1.5ex;display:block;text-decoration:none!important;visibility:hidden;text-align:center;font-weight:400}
#content h1>a.anchor::before,h2>a.anchor::before,h3>a.anchor::before,#toctitle>a.anchor::before,.sidebarblock>.content>.title>a.anchor::before,h4>a.anchor::before,h5>a.anchor::before,h6>a.anchor::before{content:"\00A7";font-size:.85em;display:block;padding-top:.1em}
#content h1:hover>a.anchor,#content h1>a.anchor:hover,h2:hover>a.anchor,h2>a.anchor:hover,h3:hover>a.anchor,#toctitle:hover>a.anchor,.sidebarblock>.content>.title:hover>a.anchor,h3>a.anchor:hover,#toctitle>a.anchor:hover,.sidebarblock>.content>.title>a.anchor:hover,h4:hover>a.anchor,h4>a.anchor:hover,h5:hover>a.anchor,h5>a.anchor:hover,h6:hover>a.anchor,h6>a.anchor:hover{visibility:visible}
#content h1>a.link,h2>a.link,h3>a.link,#toctitle>a.link,.sidebarblock>.content>.title>a.link,h4>a.link,h5>a.link,h6>a.link{color:#ba3925;text-decoration:none}
#content h1>a.link:hover,h2>a.link:hover,h3>a.link:hover,#toctitle>a.link:hover,.sidebarblock>.content>.title>a.link:hover,h4>a.link:hover,h5>a.link:hover,h6>a.link:hover{color:#a53221}
details,.audioblock,.imageblock,.literalblock,.listingblock,.stemblock,.videoblock{margin-bottom:1.25em}
details>summary:first-of-type{cursor:pointer;display:list-item;outline:none;margin-bottom:.75em}
.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{text-rendering:optimizeLegibility;text-align:left;font-family:"Noto Serif","DejaVu Serif",serif;font-size:1rem;font-style:italic}
table.tableblock.fit-content>caption.title{white-space:nowrap;width:0}
.paragraph.lead>p,#preamble>.sectionbody>[class="paragraph"]:first-of-type p{font-size:1.21875em;line-height:1.6;color:rgba(0,0,0,.85)}
table.tableblock #preamble>.sectionbody>[class="paragraph"]:first-of-type p{font-size:inherit}
.admonitionblock>table{border-collapse:separate;border:0;background:none;width:100%}
.admonitionblock>table td.icon{text-align:center;width:80px}
.admonitionblock>table td.icon img{max-width:none}
.admonitionblock>table td.icon .title{font-weight:bold;font-family:"Open Sans","DejaVu Sans",sans-serif;text-transform:uppercase}
.admonitionblock>table td.content{padding-left:1.125em;padding-right:1.25em;border-left:1px solid #dddddf;color:rgba(0,0,0,.6)}
.admonitionblock>table td.content>:last-child>:last-child{margin-bottom:0}
.exampleblock>.content{border-style:solid;border-width:1px;border-color:#e6e6e6;margin-bottom:1.25em;padding:1.25em;background:#fff;-webkit-border-radius:4px;border-radius:4px}
.exampleblock>.content>:first-child{margin-top:0}
.exampleblock>.content>:last-child{margin-bottom:0}
.sidebarblock{border-style:solid;border-width:1px;border-color:#dbdbd6;margin-bottom:1.25em;padding:1.25em;background:#f3f3f2;-webkit-border-radius:4px;border-radius:4px}
.sidebarblock>:first-child{margin-top:0}
.sidebarblock>:last-child{margin-bottom:0}
.sidebarblock>.content>.title{color:#7a2518;margin-top:0;text-align:center}
.exampleblock>.content>:last-child>:last-child,.exampleblock>.content .olist>ol>li:last-child>:last-child,.exampleblock>.content .ulist>ul>li:last-child>:last-child,.exampleblock>.content .qlist>ol>li:last-child>:last-child,.sidebarblock>.content>:last-child>:last-child,.sidebarblock>.content .olist>ol>li:last-child>:last-child,.sidebarblock>.content .ulist>ul>li:last-child>:last-child,.sidebarblock>.content .qlist>ol>li:last-child>:last-child{margin-bottom:0}
.literalblock pre,.listingblock>.content>pre{-webkit-border-radius:4px;border-radius:4px;word-wrap:break-word;overflow-x:auto;padding:1em;font-size:.8125em}
@media screen and (min-width:768px){.literalblock pre,.listingblock>.content>pre{font-size:.90625em}}
@media screen and (min-width:1280px){.literalblock pre,.listingblock>.content>pre{font-size:1em}}
.literalblock.output pre{color:#f7f7f8;background:rgba(0,0,0,.9)}
.listingblock>.content>pre:not(.highlight),.listingblock>.content>pre[class="highlight"],.listingblock>.content>pre[class^="highlight "]{background:#f7f7f8}
.listingblock>.content{position:relative}
.listingblock code[data-lang]::before{display:none;content:attr(data-lang);position:absolute;font-size:.75em;top:.425rem;right:.5rem;line-height:1;text-transform:uppercase;color:inherit;opacity:.5}
.listingblock:hover code[data-lang]::before{display:block}
.listingblock.terminal pre .command::before{content:attr(data-prompt);padding-right:.5em;color:inherit;opacity:.5}
.listingblock.terminal pre .command:not([data-prompt])::before{content:"$"}
.listingblock pre.highlightjs{padding:0}
.listingblock pre.highlightjs>code{padding:1em;-webkit-border-radius:4px;border-radius:4px}
.listingblock pre.prettyprint{border-width:0}
.prettyprint{background:#f7f7f8}
pre.prettyprint .linenums{line-height:1.45;margin-left:2em}
pre.prettyprint li{background:none;list-style-type:inherit;padding-left:0}
pre.prettyprint li code[data-lang]::before{opacity:1}
pre.prettyprint li:not(:first-child) code[data-lang]::before{display:none}
table.linenotable{border-collapse:separate;border:0;margin-bottom:0;background:none}
table.linenotable td[class]{color:inherit;vertical-align:top;padding:0;line-height:inherit;white-space:normal}
table.linenotable td.code{padding-left:.75em}
table.linenotable td.linenos{border-right:1px solid currentColor;opacity:.35;padding-right:.5em}
pre.pygments .lineno{border-right:1px solid currentColor;opacity:.35;display:inline-block;margin-right:.75em}
pre.pygments .lineno::before{content:"";margin-right:-.125em}
.quoteblock{margin:0 1em 1.25em 1.5em;display:table}
.quoteblock>.title{margin-left:-1.5em;margin-bottom:.75em}
.quoteblock blockquote,.quoteblock p{color:rgba(0,0,0,.85);font-size:1.15rem;line-height:1.75;word-spacing:.1em;letter-spacing:0;font-style:italic;text-align:justify}
.quoteblock blockquote{margin:0;padding:0;border:0}
.quoteblock blockquote::before{content:"\201c";float:left;font-size:2.75em;font-weight:bold;line-height:.6em;margin-left:-.6em;color:#7a2518;text-shadow:0 1px 2px rgba(0,0,0,.1)}
.quoteblock blockquote>.paragraph:last-child p{margin-bottom:0}
.quoteblock .attribution{margin-top:.75em;margin-right:.5ex;text-align:right}
.verseblock{margin:0 1em 1.25em}
.verseblock pre{font-family:"Open Sans","DejaVu Sans",sans;font-size:1.15rem;color:rgba(0,0,0,.85);font-weight:300;text-rendering:optimizeLegibility}
.verseblock pre strong{font-weight:400}
.verseblock .attribution{margin-top:1.25rem;margin-left:.5ex}
.quoteblock .attribution,.verseblock .attribution{font-size:.9375em;line-height:1.45;font-style:italic}
.quoteblock .attribution br,.verseblock .attribution br{display:none}
.quoteblock .attribution cite,.verseblock .attribution cite{display:block;letter-spacing:-.025em;color:rgba(0,0,0,.6)}
.quoteblock.abstract blockquote::before,.quoteblock.excerpt blockquote::before,.quoteblock .quoteblock blockquote::before{display:none}
.quoteblock.abstract blockquote,.quoteblock.abstract p,.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{line-height:1.6;word-spacing:0}
.quoteblock.abstract{margin:0 1em 1.25em;display:block}
.quoteblock.abstract>.title{margin:0 0 .375em;font-size:1.15em;text-align:center}
.quoteblock.excerpt,.quoteblock .quoteblock{margin:0 0 1.25em;padding:0 0 .25em 1em;border-left:.25em solid #dddddf}
.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{color:inherit;font-size:1.0625rem}
.quoteblock.excerpt .attribution,.quoteblock .quoteblock .attribution{color:inherit;text-align:left;margin-right:0}
table.tableblock{max-width:100%;border-collapse:separate}
p.tableblock:last-child{margin-bottom:0}
td.tableblock>.content{margin-bottom:-1.25em}
table.tableblock,th.tableblock,td.tableblock{border:0 solid #dedede}
table.grid-all>thead>tr>.tableblock,table.grid-all>tbody>tr>.tableblock{border-width:0 1px 1px 0}
table.grid-all>tfoot>tr>.tableblock{border-width:1px 1px 0 0}
table.grid-cols>*>tr>.tableblock{border-width:0 1px 0 0}
table.grid-rows>thead>tr>.tableblock,table.grid-rows>tbody>tr>.tableblock{border-width:0 0 1px}
table.grid-rows>tfoot>tr>.tableblock{border-width:1px 0 0}
table.grid-all>*>tr>.tableblock:last-child,table.grid-cols>*>tr>.tableblock:last-child{border-right-width:0}
table.grid-all>tbody>tr:last-child>.tableblock,table.grid-all>thead:last-child>tr>.tableblock,table.grid-rows>tbody>tr:last-child>.tableblock,table.grid-rows>thead:last-child>tr>.tableblock{border-bottom-width:0}
table.frame-all{border-width:1px}
table.frame-sides{border-width:0 1px}
table.frame-topbot,table.frame-ends{border-width:1px 0}
table.stripes-all tr,table.stripes-odd tr:nth-of-type(odd),table.stripes-even tr:nth-of-type(even),table.stripes-hover tr:hover{background:#f8f8f7}
th.halign-left,td.halign-left{text-align:left}
th.halign-right,td.halign-right{text-align:right}
th.halign-center,td.halign-center{text-align:center}
th.valign-top,td.valign-top{vertical-align:top}
th.valign-bottom,td.valign-bottom{vertical-align:bottom}
th.valign-middle,td.valign-middle{vertical-align:middle}
table thead th,table tfoot th{font-weight:bold}
tbody tr th{display:table-cell;line-height:1.6;background:#f7f8f7}
tbody tr th,tbody tr th p,tfoot tr th,tfoot tr th p{color:rgba(0,0,0,.8);font-weight:bold}
p.tableblock>code:only-child{background:none;padding:0}
p.tableblock{font-size:1em}
ol{margin-left:1.75em}
ul li ol{margin-left:1.5em}
dl dd{margin-left:1.125em}
dl dd:last-child,dl dd:last-child>:last-child{margin-bottom:0}
ol>li p,ul>li p,ul dd,ol dd,.olist .olist,.ulist .ulist,.ulist .olist,.olist .ulist{margin-bottom:.625em}
ul.checklist,ul.none,ol.none,ul.no-bullet,ol.no-bullet,ol.unnumbered,ul.unstyled,ol.unstyled{list-style-type:none}
ul.no-bullet,ol.no-bullet,ol.unnumbered{margin-left:.625em}
ul.unstyled,ol.unstyled{margin-left:0}
ul.checklist{margin-left:.625em}
ul.checklist li>p:first-child>.fa-square-o:first-child,ul.checklist li>p:first-child>.fa-check-square-o:first-child{width:1.25em;font-size:.8em;position:relative;bottom:.125em}
ul.checklist li>p:first-child>input[type="checkbox"]:first-child{margin-right:.25em}
ul.inline{display:-ms-flexbox;display:-webkit-box;display:flex;-ms-flex-flow:row wrap;-webkit-flex-flow:row wrap;flex-flow:row wrap;list-style:none;margin:0 0 .625em -1.25em}
ul.inline>li{margin-left:1.25em}
.unstyled dl dt{font-weight:400;font-style:normal}
ol.arabic{list-style-type:decimal}
ol.decimal{list-style-type:decimal-leading-zero}
ol.loweralpha{list-style-type:lower-alpha}
ol.upperalpha{list-style-type:upper-alpha}
ol.lowerroman{list-style-type:lower-roman}
ol.upperroman{list-style-type:upper-roman}
ol.lowergreek{list-style-type:lower-greek}
.hdlist>table,.colist>table{border:0;background:none}
.hdlist>table>tbody>tr,.colist>table>tbody>tr{background:none}
td.hdlist1,td.hdlist2{vertical-align:top;padding:0 .625em}
td.hdlist1{font-weight:bold;padding-bottom:1.25em}
.literalblock+.colist,.listingblock+.colist{margin-top:-.5em}
.colist td:not([class]):first-child{padding:.4em .75em 0;line-height:1;vertical-align:top}
.colist td:not([class]):first-child img{max-width:none}
.colist td:not([class]):last-child{padding:.25em 0}
.thumb,.th{line-height:0;display:inline-block;border:solid 4px #fff;-webkit-box-shadow:0 0 0 1px #ddd;box-shadow:0 0 0 1px #ddd}
.imageblock.left{margin:.25em .625em 1.25em 0}
.imageblock.right{margin:.25em 0 1.25em .625em}
.imageblock>.title{margin-bottom:0}
.imageblock.thumb,.imageblock.th{border-width:6px}
.imageblock.thumb>.title,.imageblock.th>.title{padding:0 .125em}
.image.left,.image.right{margin-top:.25em;margin-bottom:.25em;display:inline-block;line-height:0}
.image.left{margin-right:.625em}
.image.right{margin-left:.625em}
a.image{text-decoration:none;display:inline-block}
a.image object{pointer-events:none}
sup.footnote,sup.footnoteref{font-size:.875em;position:static;vertical-align:super}
sup.footnote a,sup.footnoteref a{text-decoration:none}
sup.footnote a:active,sup.footnoteref a:active{text-decoration:underline}
#footnotes{padding-top:.75em;padding-bottom:.75em;margin-bottom:.625em}
#footnotes hr{width:20%;min-width:6.25em;margin:-.25em 0 .75em;border-width:1px 0 0}
#footnotes .footnote{padding:0 .375em 0 .225em;line-height:1.3334;font-size:.875em;margin-left:1.2em;margin-bottom:.2em}
#footnotes .footnote a:first-of-type{font-weight:bold;text-decoration:none;margin-left:-1.05em}
#footnotes .footnote:last-of-type{margin-bottom:0}
#content #footnotes{margin-top:-.625em;margin-bottom:0;padding:.75em 0}
.gist .file-data>table{border:0;background:#fff;width:100%;margin-bottom:0}
.gist .file-data>table td.line-data{width:99%}
div.unbreakable{page-break-inside:avoid}
.big{font-size:larger}
.small{font-size:smaller}
.underline{text-decoration:underline}
.overline{text-decoration:overline}
.line-through{text-decoration:line-through}
.aqua{color:#00bfbf}
.aqua-background{background:#00fafa}
.black{color:#000}
.black-background{background:#000}
.blue{color:#0000bf}
.blue-background{background:#0000fa}
.fuchsia{color:#bf00bf}
.fuchsia-background{background:#fa00fa}
.gray{color:#606060}
.gray-background{background:#7d7d7d}
.green{color:#006000}
.green-background{background:#007d00}
.lime{color:#00bf00}
.lime-background{background:#00fa00}
.maroon{color:#600000}
.maroon-background{background:#7d0000}
.navy{color:#000060}
.navy-background{background:#00007d}
.olive{color:#606000}
.olive-background{background:#7d7d00}
.purple{color:#600060}
.purple-background{background:#7d007d}
.red{color:#bf0000}
.red-background{background:#fa0000}
.silver{color:#909090}
.silver-background{background:#bcbcbc}
.teal{color:#006060}
.teal-background{background:#007d7d}
.white{color:#bfbfbf}
.white-background{background:#fafafa}
.yellow{color:#bfbf00}
.yellow-background{background:#fafa00}
span.icon>.fa{cursor:default}
a span.icon>.fa{cursor:inherit}
.admonitionblock td.icon [class^="fa icon-"]{font-size:2.5em;text-shadow:1px 1px 2px rgba(0,0,0,.5);cursor:default}
.admonitionblock td.icon .icon-note::before{content:"\f05a";color:#19407c}
.admonitionblock td.icon .icon-tip::before{content:"\f0eb";text-shadow:1px 1px 2px rgba(155,155,0,.8);color:#111}
.admonitionblock td.icon .icon-warning::before{content:"\f071";color:#bf6900}
.admonitionblock td.icon .icon-caution::before{content:"\f06d";color:#bf3400}
.admonitionblock td.icon .icon-important::before{content:"\f06a";color:#bf0000}
.conum[data-value]{display:inline-block;color:#fff!important;background:rgba(0,0,0,.8);-webkit-border-radius:100px;border-radius:100px;text-align:center;font-size:.75em;width:1.67em;height:1.67em;line-height:1.67em;font-family:"Open Sans","DejaVu Sans",sans-serif;font-style:normal;font-weight:bold}
.conum[data-value] *{color:#fff!important}
.conum[data-value]+b{display:none}
.conum[data-value]::after{content:attr(data-value)}
pre .conum[data-value]{position:relative;top:-.125em}
b.conum *{color:inherit!important}
.conum:not([data-value]):empty{display:none}
dt,th.tableblock,td.content,div.footnote{text-rendering:optimizeLegibility}
h1,h2,p,td.content,span.alt{letter-spacing:-.01em}
p strong,td.content strong,div.footnote strong{letter-spacing:-.005em}
p,blockquote,dt,td.content,span.alt{font-size:1.0625rem}
p{margin-bottom:1.25rem}
.sidebarblock p,.sidebarblock dt,.sidebarblock td.content,p.tableblock{font-size:1em}
.exampleblock>.content{background:#fffef7;border-color:#e0e0dc;-webkit-box-shadow:0 1px 4px #e0e0dc;box-shadow:0 1px 4px #e0e0dc}
.print-only{display:none!important}
@page{margin:1.25cm .75cm}
@media print{*{-webkit-box-shadow:none!important;box-shadow:none!important;text-shadow:none!important}
html{font-size:80%}
a{color:inherit!important;text-decoration:underline!important}
a.bare,a[href^="#"],a[href^="mailto:"]{text-decoration:none!important}
a[href^="http:"]:not(.bare)::after,a[href^="https:"]:not(.bare)::after{content:"(" attr(href) ")";display:inline-block;font-size:.875em;padding-left:.25em}
abbr[title]::after{content:" (" attr(title) ")"}
pre,blockquote,tr,img,object,svg{page-break-inside:avoid}
thead{display:table-header-group}
svg{max-width:100%}
p,blockquote,dt,td.content{font-size:1em;orphans:3;widows:3}
h2,h3,#toctitle,.sidebarblock>.content>.title{page-break-after:avoid}
#toc,.sidebarblock,.exampleblock>.content{background:none!important}
#toc{border-bottom:1px solid #dddddf!important;padding-bottom:0!important}
body.book #header{text-align:center}
body.book #header>h1:first-child{border:0!important;margin:2.5em 0 1em}
body.book #header .details{border:0!important;display:block;padding:0!important}
body.book #header .details span:first-child{margin-left:0!important}
body.book #header .details br{display:block}
body.book #header .details br+span::before{content:none!important}
body.book #toc{border:0!important;text-align:left!important;padding:0!important;margin:0!important}
body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-break-before:always}
.listingblock code[data-lang]::before{display:block}
#footer{padding:0 .9375em}
.hide-on-print{display:none!important}
.print-only{display:block!important}
.hide-for-print{display:none!important}
.show-for-print{display:inherit!important}}
@media print,amzn-kf8{#header>h1:first-child{margin-top:1.25rem}
.sect1{padding:0!important}
.sect1+.sect1{border:0}
#footer{background:none}
#footer-text{color:rgba(0,0,0,.6);font-size:.9em}}
@media amzn-kf8{#header,#content,#footnotes,#footer{padding:0}}
</style>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">
<link rel="stylesheet" href="highlight_mod.css">
</head>
<body class="article toc2 toc-left">
<div id="header">
<h1>Highlight Support for Asciidoctor</h1>
<div class="details">
<span id="author" class="author">Tristano Ajmone</span><br>
<span id="email" class="email"><a href="mailto:tajmone@gmail.com">tajmone@gmail.com</a></span><br>
<span id="revnumber">version 1,</span>
<span id="revdate">2019-04-12</span>
</div>
<div id="toc" class="toc2">
<div id="toctitle">Table of Contents</div>
<ul class="sectlevel1">
<li><a href="#_introduction">Introduction</a></li>
<li><a href="#_folder_contents">Folder Contents</a></li>
<li><a href="#_original_vs_modded_extension">Original vs Modded Extension</a>
<ul class="sectlevel2">
<li><a href="#_custom_css_and_multiple_themes">Custom CSS and Multiple Themes</a></li>
<li><a href="#_substitutions">Substitutions</a></li>
<li><a href="#_highlight_datadir_enforcement"><code>HIGHLIGHT_DATADIR</code> Enforcement</a></li>
</ul>
</li>
<li><a href="#_missing_features">Missing Features</a>
<ul class="sectlevel2">
<li><a href="#_callouts">Callouts</a></li>
<li><a href="#_code_inside_tables">Code Inside Tables</a></li>
</ul>
</li>
<li><a href="#_development_roadmap">Development Roadmap</a></li>
<li><a href="#_credits">Credits</a>
<ul class="sectlevel2">
<li><a href="#_asciidoctor_highlight_extensions">Asciidoctor Highlight Extensions</a></li>
<li><a href="#_asciidoctor_haml_templates">Asciidoctor Haml Templates</a></li>
<li><a href="#_base16_color_schemes">Base16 Color Schemes</a></li>
<li><a href="#_base16_sass">Base16 Sass</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div id="content">
<div id="preamble">
<div class="sectionbody">
<div class="paragraph">
<p>Asciidoctor extensions to support syntax highlighting via Highlight in the HTML backend.</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>highlight-treeprocessor.rb</code></p>
</li>
<li>
<p><code>highlight-treeprocessor_mod.rb</code> v1.3.0 (2019-03-30)</p>
</li>
</ul>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_introduction"><a class="anchor" href="#_introduction"></a>Introduction</h2>
<div class="sectionbody">
<div class="paragraph">
<p>AsciiDoc is a very powerful documentation markup syntax for writing documents and books in plaintext sources files which can be version controlled and converted to HTML5, DocBook, PDF, and many other formats&#8201;&#8212;&#8201;think markdown with tons of extra features.</p>
</div>
<div class="paragraph">
<p>The most used AsciiDoc implementation today is
<a href="https://asciidoctor.org/" title="visit Asciidoctor (Ruby) website" target="_blank" rel="noopener">Asciidoctor</a>,
the Ruby successors of the original Python
<a href="http://asciidoc.org//" title="visit AsciiDoc (Python) website" target="_blank" rel="noopener">AsciiDoc</a>.
Asciidoctor is a fast, open source AsciiDoc text processor and publishing toolchain, with a rich echosystem of additional tools, extensions and resources.</p>
</div>
<div class="paragraph">
<p>Unfortunately, Asciidoctor doesn&#8217;t natively support using Highlight for coloring code blocks in documentation, although other highlighters are natively supported.</p>
</div>
<div class="paragraph">
<p>However, the Asciidoctor team has published on the
<a href="https://github.com/asciidoctor/asciidoctor-extensions-lab">Asciidoctor Extensions Lab</a>
project an
<a href="https://asciidoctor.org/docs/user-manual/#extensions" title="Read more about this topic in the Asciidoctor official Documentation" target="_blank" rel="noopener">extension</a>
called <strong>HighlightTreeprocessor</strong> that adds some basic support for Highlight integration:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><a href="https://github.com/asciidoctor/asciidoctor-extensions-lab/blob/master/lib/highlight-treeprocessor.rb" class="bare">https://github.com/asciidoctor/asciidoctor-extensions-lab/blob/master/lib/highlight-treeprocessor.rb</a></p>
</li>
</ul>
</div>
<div class="paragraph">
<p>In this folder I&#8217;ll be including and documenting both the original extension as well as a tweaked version which I use in many documentation projects.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_folder_contents"><a class="anchor" href="#_folder_contents"></a>Folder Contents</h2>
<div class="sectionbody">
<div class="hdlist">
<table>
<tr>
<td class="hdlist1">
<a href="./highlight-treeprocessor.rb" title="View the original HighlightTreeprocessor extension"><code>highlight-treeprocessor.rb</code></a> 
</td>
<td class="hdlist2">
<p>The original extension.</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<a href="./highlight-treeprocessor_mod.rb" title="View the modded HighlightTreeprocessor extension"><code>highlight-treeprocessor_mod.rb</code></a> 
</td>
<td class="hdlist2">
<p>The modded extension.</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<a href="./example.asciidoc" title="Example of using the original HighlightTreeprocessor extension"><code>example.asciidoc</code></a></br><a href="./example.html" title="Example of using the original HighlightTreeprocessor extension"><code>example.html</code></a> 
</td>
<td class="hdlist2">
<p>Original extension usage example.</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<a href="./example_mod.asciidoc" title="Example of using the modded HighlightTreeprocessor extension"><code>example_mod.asciidoc</code></a></br><a href="./example_mod.html" title="Example of using the modded HighlightTreeprocessor extension"><code>example_mod.html</code></a></br><a href="./example_mod.css" title="Highlight styles for modded extension example"><code>example_mod.css</code></a> 
</td>
<td class="hdlist2">
<p>Modded extension usage example.</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<a href="./haml/block_listing.html.haml" title="Custom haml template for using the modded HighlightTreeprocessor extension"><code>/haml/block_listing.html.haml</code></a></br>shared 
</td>
<td class="hdlist2">
<p>Asciidoctor assets for the modded extension (only required during conversion).</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<a href="./sass" title="Sass sources for styling Highlight themes"><code>/sass/</code></a> 
</td>
<td class="hdlist2">
<p>Sass sources and assets to customize the Highlight CSS themes for the modded extension examples.</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<a href="./build.sh" title="Script to convert the examples from AsciiDoc to HTML"><code>build.sh</code></a> 
</td>
<td class="hdlist2">
<p>Converts the examples from AsciiDoc to HTML</p>
</td>
</tr>
</table>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_original_vs_modded_extension"><a class="anchor" href="#_original_vs_modded_extension"></a>Original vs Modded Extension</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Here&#8217;s a comparison table of the differences between the original extension and my modded version:</p>
</div>
<table class="tableblock frame-all grid-all fit-content">
<colgroup>
<col>
<col>
<col>
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">feature</th>
<th class="tableblock halign-center valign-top">original</th>
<th class="tableblock halign-center valign-top">modded</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">linenums</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">&check;</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">&check;</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">subs</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><span class="red">&cross;</span></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">&check;</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">external CSS</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><span class="red">&cross;</span></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">&check;</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">multiple themes</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><span class="red">&cross;</span></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">&check;</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">callouts</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><span class="red">&cross;</span></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><span class="red">&cross;</span></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">code in tables</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><span class="red">&cross;</span></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><span class="red">&cross;</span></p></td>
</tr>
</tbody>
</table>
<div class="sect2">
<h3 id="_custom_css_and_multiple_themes"><a class="anchor" href="#_custom_css_and_multiple_themes"></a>Custom CSS and Multiple Themes</h3>
<div class="paragraph">
<p>The reason I&#8217;ve tweaked the original extension was to allow using custom CSS stylesheets to provide each language with its own theme, instead of having a single coloring theme for every code block in the document.
This is the main difference between the original extension and my modded version, and it comes at the price of having to provide your own CSS to the document&#8201;&#8212;&#8201;while the original extension will automatically inject into the document the CSS of an Highlight theme.</p>
</div>
<div class="paragraph">
<p>So, if you&#8217;re happy highlighting all the code with one of Highlight native themes, then you should use the original <strong>HighlightTreeprocessor</strong> extension; but if you&#8217;d like more control over CSS styles, and to theme each language separately, then the modded extension is the way to go.</p>
</div>
<div class="paragraph">
<p>In the <a href="./sass" title="Sass sources for styling Highlight themes"><code>/sass/</code></a> folder you&#8217;ll find some useful Sass/SCSS templates and examples on how to easily create multiple themes targeting specific languages.</p>
</div>
</div>
<div class="sect2">
<h3 id="_substitutions"><a class="anchor" href="#_substitutions"></a>Substitutions</h3>
<div class="paragraph">
<p>The other main difference is that the modded extension supports
<a href="https://asciidoctor.org/docs/user-manual/#subs" title="Read more about this topic in the Asciidoctor official Documentation" target="_blank" rel="noopener">substitutions</a>
in the code block.</p>
</div>
<div class="exampleblock">
<div class="title">Example 1. Code with substitutions</div>
<div class="content">
<div class="literalblock">
<div class="title">Asciidoc source</div>
<div class="content">
<pre>[source,alan,subs=quotes]
------------------------
The 'dance hall' #IsA location#
  Description
    "The hall is #_bigger_ than you expected#, and
     far too crowded. You feel the urge to leave."
End the.
------------------------</pre>
</div>
</div>
<div class="listingblock">
<div class="title">HTML result</div>
<div class="content">
<pre class="highlight" lang="alan"><code class="language-alan" data-lang="alan"><span class="hl kwa">The</span> &apos;dance hall&apos; <mark><span class="hl kwa">IsA</span> <span class="hl kwb">location</span></mark>&#x000A;  <span class="hl kwa">Description</span>&#x000A;    <span class="hl str">&quot;The hall is <mark><em>bigger</em> than you expected</mark>, and</span>&#x000A;<span class="hl str">     far too crowded. You feel the urge to leave.&quot;</span>&#x000A;<span class="hl kwa">End the.</span></code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_highlight_datadir_enforcement"><a class="anchor" href="#_highlight_datadir_enforcement"></a><code>HIGHLIGHT_DATADIR</code> Enforcement</h3>
<div class="paragraph">
<p>Another extra (optional) feature of the modded extension is that, if the <code>HIGHLIGHT_DATADIR</code> environment variable is set, it will enforce it by invoking Highlight with the <code>--data-dir=&lt;HIGHLIGHT_DATADIR&gt;</code> option so that it gets the highest override priority.</p>
</div>
<div class="paragraph">
<p>This ensures that custom langDefs inside <code>HIGHLIGHT_DATADIR</code> will always override the predefined ones, whereas ordinarily the path of the <code>HIGHLIGHT_DATADIR</code> env var would be searched <em>after</em> Highlight installation folder.</p>
</div>
<div class="paragraph">
<p>Since it&#8217;s not possible to control the <code>--data-dir</code> option from within AsciiDoc documents, this hardcoded workaround is a convenient solution for projects which need to override Highlight default configurations.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_missing_features"><a class="anchor" href="#_missing_features"></a>Missing Features</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Neither the original nor my modded version of the extension support callouts or highlighting listing blocks inside tables.</p>
</div>
<div class="sect2">
<h3 id="_callouts"><a class="anchor" href="#_callouts"></a>Callouts</h3>
<div class="paragraph">
<p>The extension doesn&#8217;t currently process callouts, and Asciidoctor will raise a warning if you use them (indeed, the <a href="./build.sh" title="Script to convert the examples from AsciiDoc to HTML"><code>build.sh</code></a> script to convert this document does warn about missing callouts).</p>
</div>
<div class="exampleblock">
<div class="title">Example 2. Code with callouts</div>
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlight" lang="alan"><code class="language-alan" data-lang="alan"><span class="hl kwa">The</span> &apos;dance hall&apos; <span class="hl kwa">IsA</span> <span class="hl kwb">location</span> <span class="hl opt">&lt;</span><span class="hl num">1</span><span class="hl opt">&gt;&lt;</span><span class="hl num">2</span><span class="hl opt">&gt;</span>&#x000A;  <span class="hl kwa">Description</span> <span class="hl opt">&lt;</span><span class="hl num">3</span><span class="hl opt">&gt;</span>&#x000A;    <span class="hl str">&quot;The hall is bigger_ than you expected, and</span>&#x000A;<span class="hl str">     far too crowded. You feel the urge to leave.&quot;</span>&#x000A;<span class="hl kwa">End the.</span></code></pre>
</div>
</div>
<div class="colist arabic">
<table>
<tr>
<td><i class="conum" data-value="1"></i><b>1</b></td>
<td><code>'dance hall'</code> is a quoted identifier, it will be show as the location name.</td>
</tr>
<tr>
<td><i class="conum" data-value="2"></i><b>2</b></td>
<td>The dance hall is an instance of the <code>location</code> class.</td>
</tr>
<tr>
<td><i class="conum" data-value="3"></i><b>3</b></td>
<td>The <code>Description</code> of a location will be shown every time the player enters the room or examines it via the <code>look</code> verb.</td>
</tr>
</table>
</div>
</div>
</div>
<div class="paragraph">
<p>In the original extension support for callouts extraction and processing was never implemented.
I&#8217;ve attempted to add callouts support myself, but without success.</p>
</div>
</div>
<div class="sect2">
<h3 id="_code_inside_tables"><a class="anchor" href="#_code_inside_tables"></a>Code Inside Tables</h3>
<div class="paragraph">
<p>Listing blocks inside table cells are not processed by the treeprocessor extension.
The listing block will just get some basic styling but the code won&#8217;t be processed by Highlight.</p>
</div>
<div class="exampleblock">
<div class="title">Example 3. Code listing inside a table cell</div>
<div class="content">
<table class="tableblock frame-all grid-all fit-content">
<colgroup>
<col>
<col>
</colgroup>
<thead>
<tr>
<th class="tableblock halign-center valign-top">problem</th>
<th class="tableblock halign-left valign-top">example</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Listing blocks inside tables won&#8217;t be highlighted.</p></td>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p>This Lua block isn&#8217;t processed by Highlight:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight" lang="lua"><code class="language-lua" data-lang="lua">if newState==HL_KEYWORD and kwgroup==5 then&#x000A;  AddKeyword(token, 5)&#x000A;end</code></pre>
</div>
</div></div></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>In the above table the rightmost column is set to be styled as AsciiDoc (using the <code>a</code> specifier):</p>
</div>
<div class="literalblock">
<div class="content">
<pre>[cols="1*&lt;d,1*&lt;a",options="header,autowidth"]</pre>
</div>
</div>
<div class="paragraph">
<p>But the treeprocessor extension doesn&#8217;t process listings inside table cells.</p>
</div>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
For more details regarding this limitation, see Dan Allen&#8217;s reply in
<a href="https://github.com/asciidoctor/asciidoctor/issues/2990" target="_blank" rel="noopener">Issue #2990</a>.
</td>
</tr>
</table>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_development_roadmap"><a class="anchor" href="#_development_roadmap"></a>Development Roadmap</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Bringing full Highlight support to Asciidoctor has always ranked high in my priorities list since I work a lot with code documentation and I enjoy the power of AsciiDoc.
Unfortunately, I don&#8217;t have any knowledge of Ruby and the Asciidoctor API, so all my tweaks to the <strong>HighlightTreeprocessor</strong> extension so far are nothing more than trial and error attempts to hack my way through it.</p>
</div>
<div class="paragraph">
<p>Lack of support for callouts is a serious limitation which hinders using Highlight in Asciidoctor projects&#8201;&#8212;&#8201;or the other way around, hinder using Asciidoctor in project which depend on Highlight.
I&#8217;ve tried several times to add callouts support to the <strong>HighlightTreeprocessor</strong> extension, but to no avail.</p>
</div>
<div class="paragraph">
<p>Also, as Dan Allen pointed out to me in
<a href="https://github.com/asciidoctor/asciidoctor/issues/2990" target="_blank" rel="noopener">Issue #2990</a>,
the new Asciidoctor API makes the approach of the <strong>HighlightTreeprocessor</strong> extension somewhat obsolete:</p>
</div>
<div class="quoteblock">
<blockquote>
<div class="paragraph">
<p>Asciidoctor 2.0 introduces a new API for registering a syntax highlighter adapter. I recommend that you use this for your highlight extension. Here&#8217;s an example:</p>
</div>
<div class="paragraph">
<p><a href="https://github.com/asciidoctor/asciidoctor/blob/master/lib/asciidoctor/syntax_highlighter/coderay.rb" class="bare">https://github.com/asciidoctor/asciidoctor/blob/master/lib/asciidoctor/syntax_highlighter/coderay.rb</a></p>
</div>
<div class="paragraph">
<p>Instead of having to find nodes in a tree processor extension, the adapter gets called by the processor to highlight the relevant nodes, contribution markup to the output, and write a custom stylesheet.</p>
</div>
<div class="paragraph">
<p>You can find the API docs here:</p>
</div>
<div class="paragraph">
<p><a href="https://github.com/asciidoctor/asciidoctor/blob/master/lib/asciidoctor/syntax_highlighter.rb" class="bare">https://github.com/asciidoctor/asciidoctor/blob/master/lib/asciidoctor/syntax_highlighter.rb</a></p>
</div>
</blockquote>
<div class="attribution">
&#8212; Dan Allen (@mojavelinux)<br>
<cite>Issue #2990 at asciidoctor</cite>
</div>
</div>
<div class="paragraph">
<p>So, ultimately, any further development in the direction of fully supporting Highlight in Asciidoctor (whether natively or by a third party extension) will need to shift to the new Asciidoctor 2.0 API.</p>
</div>
<div class="paragraph">
<p>Hopefully, someone with more Ruby competence than me will take on this task, and soon we might see Highlight natively supported by Asciidoctor.
In the meantime, I haven&#8217;t given up on this goal, and I&#8217;ll be trying to learn a bit of Ruby and study the new Asciidoctor API, and see where I can get.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_credits"><a class="anchor" href="#_credits"></a>Credits</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Due credits and licenses for third party assets used in this directory tree.</p>
</div>
<div class="sect2">
<h3 id="_asciidoctor_highlight_extensions"><a class="anchor" href="#_asciidoctor_highlight_extensions"></a>Asciidoctor Highlight Extensions</h3>
<div class="ulist">
<ul>
<li>
<p><a href="./highlight-treeprocessor.rb" title="View the original HighlightTreeprocessor extension"><code>highlight-treeprocessor.rb</code></a></p>
</li>
<li>
<p><a href="./highlight-treeprocessor_mod.rb" title="View the modded HighlightTreeprocessor extension"><code>highlight-treeprocessor_mod.rb</code></a></p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The file <code>highlight-treeprocessor.rb</code> was taken from the
<a href="https://github.com/asciidoctor/asciidoctor-extensions-lab" title="Visit the Asciidoctor  Extensions Lab project" target="_blank" rel="noopener"><strong>Asciidoctor Extensions Lab</strong></a>
project (commit <code>18bdf62</code>), Copyright &#169; 2014-2016
The Asciidoctor Project, released under MIT License:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>The MIT License

Copyright (C) 2014-2016 The Asciidoctor Project</pre>
</div>
</div>
<div class="paragraph">
<p>The <code>highlight-treeprocessor_mod.rb</code> file was adapted by Tristano Ajmone from the original file <code>highlight-treeprocessor.rb</code>, also released under MIT License:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>The MIT License

Copyright (C) 2018 Tristano Ajmone.
Copyright (C) 2014-2016 The Asciidoctor Project

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.</pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_asciidoctor_haml_templates"><a class="anchor" href="#_asciidoctor_haml_templates"></a>Asciidoctor Haml Templates</h3>
<div class="ulist">
<ul>
<li>
<p><a href="./haml" title="Custom Haml templates for the Asciidoctor HTML5 backend"><code>/haml/</code></a></p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The files inside the <code>/haml/</code> folder were adapted by Tristano Ajmone from the original
<a href="https://github.com/asciidoctor/asciidoctor-backends/tree/master/haml/html5" target="_blank" rel="noopener">Haml HTML5 templates</a>
taken from the
<a href="https://github.com/asciidoctor/asciidoctor-backends" title="Visit the Asciidoctor Backends project" target="_blank" rel="noopener"><strong>Asciidoctor Backends</strong></a>
project, Copyright &#169; 2012-2016 Dan Allen and the Asciidoctor Project, released under MIT License:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>The MIT License

Copyright (C) 2018 Tristano Ajmone.
Copyright (C) 2012-2016 Dan Allen and the Asciidoctor Project

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.</pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_base16_color_schemes"><a class="anchor" href="#_base16_color_schemes"></a>Base16 Color Schemes</h3>
<div class="paragraph">
<p>The Sass/CSS themes use the following Base16 color schemes:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><em>Base16 Eighties</em>, by <a href="http://chriskempson.com" target="_blank" rel="noopener">Chris Kempson</a></p>
</li>
<li>
<p><em>Base16 Brewer</em>, by <a href="http://github.com/tpoisot" target="_blank" rel="noopener">Timothée Poisot</a></p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The <strong>Base16</strong> project was created by Chris Kempson:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><a href="http://chriskempson.com/projects/base16/" class="bare">http://chriskempson.com/projects/base16/</a></p>
</li>
</ul>
</div>
</div>
<div class="sect2">
<h3 id="_base16_sass"><a class="anchor" href="#_base16_sass"></a>Base16 Sass</h3>
<div class="paragraph">
<p>The following Base16 SCSS files:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><a href="./sass/_base16-brewer.scss"><code>./sass/_base16-brewer.scss</code></a></p>
</li>
</ul>
</div>
<div class="paragraph">
<p>were taken from the <strong>Base16 Sass</strong> project by Tristano Ajmone:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><a href="https://github.com/tajmone/Base16-Sass" class="bare">https://github.com/tajmone/Base16-Sass</a></p>
</li>
</ul>
</div>
<div class="paragraph">
<p>also released under MIT License.</p>
</div>
<div class="literalblock">
<div class="content">
<pre>MIT License

Copyright (c) 2019 Tristano Ajmone &lt;tajmone@gmail.com&gt;
https://github.com/tajmone/Base16-Sass

Copyright (c) 2012 Chris Kempson (http://chriskempson.com)
https://github.com/chriskempson/base16-builder

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.</pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div id="footer">
<div id="footer-text">
Version 1<br>
</div>
</div>
</body>
</html>