Skip to main content

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
Re: [asciidoc-wg] AsciiDoc support of custom highlighting


This is an important topic and I'm glad you're thinking about it. However, I ask that you hold off on this discussion until the specification project and list is in place. Then you can raise the topic there. This list is for governance and administration of the working group and project formation (etc), not technical discussions. If we continue this discussion here, then we run the risk of letting a whole range of spec-related discussions into this list, which will be haphazard and create a lot of confusion. I know you're eager to get started and so am I. We're almost there.

Thanks for understanding,


On Fri, Jun 12, 2020 at 2:16 AM Didier Vojtisek <didier.vojtisek@xxxxxxxx> wrote:
Hi Alexander

yes, please add me to interested party ( and Inria )

About the code block highlighting I think this is not just an
implementation issue but this should come to the specification too.

AFAIK, the current situation is: asciidoc only specify the name of the
language for the code block, then the implementation has to find a
highlighter to deal with it. Then implementations such as asciidoctor
relies on external highlighters each of them supporting only a finite
set of languages.
- This is fine is you deal only with mainstream languages, but there is
usually no support for custom languages (or recent ones) If we stick to
Eclipse world there plenty of languages that would appreciate to have
such support (Xtext, xtend), not speaking about all the DSL (Domain
Specific Language) that are quite easy to build today or the DSLs of
many communities.
- This doesn't scale well when you need several backends (both pdf and
html for ex) leading to inconsistent presentation outputs for these blocks.

The situation back with docbook was slightly better, it allows to
specify custom language in a SyntaxHighlighters specification (cf. ) which is
used in a pre-processing phase before doing the final backend rendering

I think asciidoc should also have in its specification a part equivalent
to the syntax highlighter regardless of the implementation backends.

Didier Vojtisek

On 11/06/2020 21:29, Alexander Schwartz wrote:
> Hallo Didier,
> breaking down the implementation to different modules sounds like a best
> practive: this would keep the parsing of AsciiDoc and creating an AST
> separate from creating an output format.
> The Asciidoctor implementation already pluggable output formats (called
> backends), and this proved very valuable in different scenarios. I think
> it is a best practice this implementation should adopt. It also creates
> a block-level AST that can be inspected at run-time.
> If you are using Asciidoctor today and given some Ruby knowledge, you
> could try your luck with either a tree processor (the Asciidoctor
> extensions lab contains varios tree processors already) or a backend
> (you might want to strip down the html5 backend, see the source of
> html5.rb).
> If you have problems with Asciidoctor souce highlighting, maby as this
> question with an example in the Asciidoctor forum.
> Regarding the project proposal: If you want to add yourself as an
> interested party to try out early releases, or if you want to suggest
> requirements for the scope, please let me know.
> Regards,
> Alexander
> On 11.06.2020 14:48, Didier Vojtisek wrote:
>> Hi
>> (not sure this is the best thread)
>> what are the plan about implementation extensions in order to support
>> various output variants or complement?
>> for example, one of my daily usecase is to generate both the html and
>> the toc.xml files in order to include the generated html file in the
>> Eclipse help system.
>> As far as I known this toc.xml generation doesn't exist in
>> asciidoctor, so our current tool chain is more complex: first generate
>> the docbook from the asciidoc then use the docbook toolchain to
>> generate the complementary toc files.
>> similarly, there is also the point about supporting custom variants
>> for html such as webhelp (again a quite old output from docbook
>> toolchain but that has the good benefit to have a scalable outline/toc)
>> Best regard
>> Didier Vojtisek
>> ps: short introduction about myself:
>> I started using docbook since ~2005 to write the documentation of our
>> research tools, I moved to asciidoc as input language but regularly
>> still need to fallback to docbook toolchain due to lacks in asciidoc
>> toolchain such as the one above or the poor support of highlighting
>> for custom languages in the [source] code block
> --
> Alexander Schwartz (alexander.schwartz@xxxxxxx)
> _______________________________________________
> asciidoc-wg mailing list
> asciidoc-wg@xxxxxxxxxxx
> To unsubscribe from this list, visit

Didier Vojtisek
SED Rennes - DiverSE Team - LogicA Team
Inria, Univ Rennes, CNRS, IRISA
Campus de beaulieu
35042 Rennes
02 99 84 75 07

asciidoc-wg mailing list
To unsubscribe from this list, visit

Dan Allen, Vice President | OpenDevise Inc.
Pronouns: he, him, his
Content ∙ Strategy ∙ Community

Back to the top