"Fossies" - the Fresh Open Source Software Archive

Member "highlight-3.57-x64/extras/AsciiDoc/example_mod.asciidoc" (12 May 2020, 7167 Bytes) of package /windows/www/highlight-3.57-x64.zip:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) AsciiDoc source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the last Fossies "Diffs" side-by-side code changes report for "example_mod.asciidoc": 3.56_vs_3.57.

    1 = Modded HighlightTreeprocessor Example
    2 Tristano Ajmone <tajmone@gmail.com>
    3 include::README.asciidoc[tag=mod_revinfo]
    4 :revnumber: {modVer}
    5 :revdate: {modDate}
    6 :version-label: mod
    7 :revremark: Last edited: 2019-03-12
    8 //
    9 :toclevels: 5
   10 :toc: left
   11 :experimental: true
   12 :icons: font
   13 :linkattrs: true
   14 :reproducible: true
   15 :sectanchors:
   16 // ===================
   17 // Highlight Settings:
   18 // ===================
   19 :source-highlighter: highlight
   20 :docinfo: shared
   21 
   22 
   23 A demonstration of the modded *HighlightTreeprocessor* extension with some usage instructions.
   24 
   25 Associated files:
   26 
   27 * link:./docinfo.html[`docinfo.html`]
   28 * link:./haml/block_listing.html.haml[`/haml/block_listing.html.haml`]
   29 * link:./highlight-treeprocessor.rb[`highlight-treeprocessor_mod.rb`] {modVer}
   30 * link:./highlight_mod.css[`highlight_mod.css`]
   31 
   32 
   33 == Highlighting Previews
   34 
   35 A couple of examples of how the rendered code looks like.
   36 link:./highlight_mod.css[The custom CSS stylesheet] defines a default theme plus some dedicated themes targeting specific syntaxes.
   37 
   38 === Example 1
   39 
   40 For PureBasic code I've defined a dedicated theme mimicking the native IDE of the language.
   41 
   42 [source,purebasic]
   43 ------------------
   44 include::../langs-examples/ex-src/PureBasic.pb[]
   45 ------------------
   46 
   47 === Example 2: Line Numbers
   48 
   49 In this example we add the `linenum` option to enable line-numbering.
   50 Again, for the Alan syntax there is a dedicated CSS theme.
   51 
   52 [source,alan,linenum]
   53 ------------------
   54 include::../langs-examples/ex-src/alan.alan[]
   55 ------------------
   56 
   57 When `linenums` is used, Highlight is invoked with the `-l -j 2` options.
   58 
   59 
   60 === Example 3: Substitutions
   61 
   62 In this example we'll enable substitutions inside the listing code via the `subs=quotes` option.
   63 
   64 
   65 // tag::example_alan_substitutions[]
   66 
   67 .Asciidoc source
   68 .........................................
   69 [source,alan,subs=quotes]
   70 ------------------------
   71 The 'dance hall' #IsA location#
   72   Description
   73     "The hall is #_bigger_ than you expected#, and
   74      far too crowded. You feel the urge to leave."
   75 End the.
   76 ------------------------
   77 .........................................
   78 
   79 .HTML result
   80 [source,alan,subs=quotes]
   81 ------------------------
   82 The 'dance hall' #IsA location#
   83   Description
   84     "The hall is #_bigger_ than you expected#, and
   85      far too crowded. You feel the urge to leave."
   86 End the.
   87 ------------------------
   88 // end::example_alan_substitutions[]
   89 
   90 Text enclosed within single or double `&num;` symbols will be wrapped in the `<mark>` tag (See
   91 link:https://asciidoctor.org/docs/user-manual/#custom-styling-with-attributes[Asciidoctor Manual ยง19.5^]), which I've customized to mimic a smeared fluorescent marker.
   92 Also notice how the word '`bigger`' is rendered as emphasized text.
   93 
   94 
   95 == Usage Instructions
   96 
   97 
   98 To enable the modded *HighlightTreeprocessor* extension you must invoke Asciidoctor with the `-r` (`--require`) option:
   99 
  100 [source,bash,subs=quotes]
  101 -----------------------------------
  102 asciidoctor \
  103   ##-r ./highlight-treeprocessor_mod.rb## \
  104   -a source-highlighter=highlight \
  105   -a docinfo=shared \
  106   -T haml \
  107   example_mod.asciidoc
  108 -----------------------------------
  109 
  110 To enable using Highlight, you need to set the `source-highlighter` attribute to `highlight`.
  111 You may do so via the command line, using the `-a` (`--attribute`) option:
  112 
  113 [source,bash,subs=quotes]
  114 -----------------------------------
  115 asciidoctor \
  116   -r ./highlight-treeprocessor_mod.rb \
  117   ##-a source-highlighter=highlight## \
  118   -a docinfo=shared \
  119   -T haml \
  120   example_mod.asciidoc
  121 -----------------------------------
  122 
  123 
  124 or you can set the `source-highlighter` attribute inside the document header:
  125 
  126 ..............................
  127 :source-highlighter: highlight
  128 ..............................
  129 
  130 
  131 === Custom CSS Stylesheets
  132 
  133 Because the modded extension doesn't rely on Highlight to convert themes to CSS, you'll need to add to the output document your custom CSS.
  134 
  135 The easiest way to do so without interfering with the native stylesheet of the Asciidoctor HTML backend is to incorporate the CSS file via a
  136 link:https://asciidoctor.org/docs/user-manual/#docinfo-file[head docinfo file^,title="See Asciidoctor documentation on docinfo files"], and then enable it via the `docinfo` attribute, either in the document header:
  137 
  138 ................
  139 :docinfo: shared
  140 ................
  141 
  142 or via CLI options:
  143 
  144 [source,bash,subs=quotes]
  145 -----------------------------------
  146 asciidoctor \
  147   -r ./highlight-treeprocessor_mod.rb \
  148   -a source-highlighter=highlight \
  149   ##-a docinfo=shared## \
  150   -T haml \
  151   example_mod.asciidoc
  152 -----------------------------------
  153 
  154 
  155 The link:./docinfo.html[`docinfo.html`] file used for this document contains a single header line to load the external CSS stylesheet:
  156 
  157 
  158 [source,html]
  159 <link rel="stylesheet" href="highlight_mod.css">
  160 
  161 
  162 Further more, if you want to be able to customize themes on a per language base, and use different background colors for each theme, you'll need to use the customized Haml template provided with this example:
  163 
  164 * link:./haml/block_listing.html.haml[`/haml/block_listing.html.haml`]
  165 
  166 and tell Asciidoctor where to look for the custom templates folder via the `-T` (`--template-dir`) option:
  167 
  168 [source,bash,subs=quotes]
  169 -----------------------------------
  170 asciidoctor \
  171   -r ./highlight-treeprocessor_mod.rb \
  172   -a source-highlighter=highlight \
  173   -a docinfo=shared \
  174   ##-T haml## \
  175   example_mod.asciidoc
  176 -----------------------------------
  177 
  178 The customized template ensures that the `lang` attribute is added also to the `<pre>` tag, so it might be targeted via custom CSS:
  179 
  180 [source,html,subs=quotes]
  181 -----------------------------------
  182 <pre class="highlight" lang="alan">
  183   <code class="language-alan" data-lang="alan">
  184 -----------------------------------
  185 
  186 whereas by default Asciidoctor will only emit the `lang` attribute on the `<code>` tag:
  187 
  188 [source,html,subs=quotes]
  189 -----------------------------------
  190 <pre class="highlight">
  191   <code class="language-alan" data-lang="alan">
  192 -----------------------------------
  193 
  194 In the link:./sass[`/sass/`] folder you'll find the commented SCSS sources used by this document, and a useful Sass template for quickly generating Highlight themes targeting specific syntaxes.
  195 
  196 
  197 === Custom LangDefs
  198 
  199 If you'd like to make available to Highlight some custom langDefs, or override the native language definitions of Highlight with your same-named customized versions, you only need to set the `HIGHLIGHT_DATADIR` environment variable to point to your custom Hihglight settings folder before invoking Asciidoctor.
  200 
  201 The modded extension will check if the `HIGHLIGHT_DATADIR` environment variable is set, and if it is it will enforce it by invoking Highlight with the `--data-dir=<HIGHLIGHT_DATADIR>` option so that it gets the highest override priority.
  202 
  203 This ensures that custom langDefs inside `HIGHLIGHT_DATADIR` will always override the predefined ones, whereas ordinarily the path of the `HIGHLIGHT_DATADIR` env var would be searched _after_ Highlight installation folder.
  204 
  205 Since it's not possible to control the `--data-dir` option from within AsciiDoc documents, this hardcoded workaround is a convenient solution for projects which need to override Highlight default configurations.
  206 
  207 
  208 // EOF //