Info about the status of the various documents and project features.
Table of Contents
The following table provides status info on all the documents available in this repository:
| document | folder | highlighter | HTML | status | on website | |
|---|---|---|---|---|---|---|
| Actors in containers | /alan-design/ |
Rouge | ✓ | ✗ | WIP draft | ✓ |
| ALAN 3 Beginner's Guide | /alanguide/ |
Highlight | ✓ | ✓ | ADoc WIP | ✓ |
| Alan Design Documentation | /alan-design/ |
Rouge | ✓ | ✗ | WIP draft | ✓ |
| Alan IDE Reference Guide | /ideguide/ |
none | ✓ | ✗ | final | ✓ |
| Alan Rules | /alan-design/ |
Rouge | ✓ | ✗ | WIP draft | ✓ |
| Conversion Guide | /conversion/ |
Rouge | ✓ | ✗ | ADoc WIP | ✗ |
| The ALAN Author's Guide | /writing/ |
Highlight | ✓ | ✗ | WIP draft | ✗ |
| The ALAN Manual | /manual/ |
Rouge | ✓ | ✓ | ongoing | ✓ |
The "status" columns values indicate:
- ADoc WIP — document is not fully ported to AsciiDoc, and still needs adaptation to make full use of our toolchain, templates features, and styling conventions.
- final — there are no plans to update the document.
- ongoing — document is productions ready, but still being regularly updated and improved.
- WIP draft — document is still being written.
As you might notice from the above table, none of the documents is currently using highlight.js for syntax highlighting, but they are either using Rouge or Highlight.
Rouge is the number one highlighter choice in this project, because it supports callouts in code blocks, it's powerful, and it's natively supported by Asciidoctor's HTML backend as well as by asciidoctor-pdf (which we're planning to use once some current problems are fixed). So we've migrated to Rouge all the documents we could.
Documents still using Highlight are doing so because they contain custom styling selections within a code block using the # delimiters for text span or highlight syntax, which is currently not supported with the Rouge highlighter (when these elements are present, syntax highlighting is disabled).
This is a problem with the native Rouge adapter that ships with Asciidoctor (Ruby).
Note that these documents can't be properly converted to PDF either, because our custom templates for asciidoctor-fopub currently don't render properly highlight syntax or text spans in code blocks.
For example, the ALAN 3 Beginner's Guide makes heavy use of text spans and highlight syntax in code blocks, which won't allow us to use Rouge with it until the problem is fixed in the Asciidoctor application.
This section described the various options regarding the choice of a syntax highlighter for the HTML backend according to supported features, and describes the unsupported features for the PDF backed.
These elements are crucial for determining which AsciiDoc features to use in a source document, and how these might affect the choice of the syntax highlighter to adopt in the HTML backend, and whether these features will allow creating a well formed PDF document.
The documents in this repository can choose to use different syntax highlighters for highlighting ALAN source code in the HTML format. Each highlighter has its pros and cons, supporting some features but not others, which might ultimately be the determining factor in one documentation project choosing one highlighter over the other.
These are the supported highlighters, in order of recommendation:
Maintainers of a document in HTML format for this project should try to pick the first highlighter in the list that works well for their document; and only choose the next one if experiencing problems with features supports.
As for the PDF format, we currently support only the asciidoctor-fopub backend, which can only use its own syntax highlighter:
Custom styles and our own ALAN syntax definition are provided via the alan-xsl-fopub repository, included as a Git submodule in this project.
The following table shows the features supported by each highlighter.
NOTE — To preview and test these features, build the developer test documents found in the
_dev/styles-tests/folder.
| highlighter | ALAN block comments | alt themes | callouts | marked code |
|---|---|---|---|---|
| Rouge | ✓ | ✓ | ✓ | ✗ |
| Highlight | ✓ | ✓ | ✗ (#36) | ✓ |
| highlight.js | ✗ (TBD: #121) | ✗ (TBD: #120) | ✓ | ✓ |
| XSLTHL | ✗ | ✗ (TBD: #123) | ✓ | ✗ |
The above columns refer to:
-
ALAN block comments — ALAN Beta8 introduces block comments; pre-existing ALAN syntax definitions for highlighters need to be updated in order to support this feature.
-
alt themes — beside the default theme for ALAN code blocks, there are two alternative themes which are used by some documents in this project:
- Library (
[source,alan,role="lib"]), a dark theme to indicate that a code block is an excerpt from an existing library or extensions. - Tutorial (
[source,alan,role="tutorial"]), a very light theme used to differentiate generic code examples from code that is part of a tutorial file, i.e. excerpts from a source file that ships with the tutorial or that the reader needs to create for the sake of the tutorial.
- Library (
-
callouts — this column indicates whether callouts in code blocks are supported by the highlighter. Example:
[source,alan,subs="quotes"] ------------------------------------------------- -- "Paradise Lost" a short example in ALAN IF <1> The shore IsA location -- <2> <3> Name Shore of Great Sea Description -- <4> "A beautiful sea shore, probably Paradise lost." End the shore. ------------------------------------------------- - <1> callout text. - <2> other callout text. - <3> yet another callout text. - <4> and another callout text.
This doesn't affect support for callouts in other type of verbatim blocks (e.g. the Shell mock-up literal block), which will work as expected since the block contents won't be handled by the syntax highlighter. Example:
[literal, role="shell"] ................................................................... D:\>alan -help <1> Usage: ALAN <adventure> [-help] [options] Arguments: <adventure> -- file name, default extension '.alan' <2> <3> ...................................................................
-
marked code — indicates whether the highlighter supports custom styling selections within a code block using the
#delimiters for text span or highlight syntax. Example:[source,alan,subs="quotes"] ------------------------------------------ -- Example 1: #Yellow highlighting#. Every book IsA object. [green]#Description "It's just a book."# Has not been_read. End Every.End Every. ------------------------------------------