Syntax Highlighting in HTML about alan-docs HOT 3 CLOSED

This syntax highlighting integration for HTML backend is turning out a bit of a nightmare...

Discarding Rouge

After having looked into it, Rouge is not going to be help us as it's not currently supported in Asciidoctor (although it's 100% Ruby and was supposed to become the native highlighter).

Considering Pygments

This leaves as with Pygments as an alternative. But there are some catches here:

• Asciidoctor uses Pygments via the pygments.rb gem, which only works with Python 2 (although Pygments works with both Py 2 and Py 3!).

• Using a custom Pygment lexer (ie, Alan) requires some customized initialization before launching Asciidoctor:

  https://asciidoctor.org/docs/user-manual/#using-a-custom-pygments-installation

  I'm not sure how this is going to work on all users machines, as it requires a path to the local installation of Pygments.

  We could hope that the Alan syntax would be included soon in the official Pygments distribution and that, in turn, it gets included in the pygments.rb too (which includes Pygments in it). But that's a lot of "ifs" and "let's hopes".

Vaiable Options

I'll look into Pygments, as this would allow total freedom in terms of callouts and custom stylings over source code blocks.

Quite frankly, Highlight.js seems the easier solution right now because it's easy to integrate into the project and doesn't force anyone to install Python, Pygments, etc. Also, Highlight.js releases are fully standalone, and they should support callouts and all the rests (cross fingers). Maybe we should settle on this as a starting point.

I wish the Highlight extension was completed so it could support callouts, but not knowing Ruby there isn't much I can do about it. Asciidoctor team were already very valuable in adding support for it (it started off from a request of mine), and they even provided a base extension to start with; asking more would be too much.

Any thoughts on this mess?

from alan-docs.

I've managed to create the Alan syntax definition for Highlight.js!

I've done some testing against edgecases, but it seems to work fine. Tomorrow I'll integrate it into a test branch so I can test how it copes with callouts, etc. If it works, I'll create a custom theme for it and merge it into master branch.

Later on we could bundle with it a BNF syntax too, and maybe AsciiDoc too (for the repo's documentation, which contains AsciiDoc examples).

Before submitting it to the highlight.js repo I want to test it further.

But I'd say we're at a good point here.

from alan-docs.

Ciao @thoni56,

It's been a hard day, but It's mission accomplished.

Highlight.js Integration

I've succesfully created an Alan definition for highlight.js, and integrated it into the project:

• https://github.com/alan-if/alan-docs/tree/master/_assets/hjs

I've also created a PR for it to be included in the official distribution, so hopefully its utility will go beyond this project too.

I've update the typography test documents to check if callouts are handled well in both PDF and HTML5 syntax-highlighter blocks, and they are.

Now the HTML version of the Manual is syntax highlighted (only Alan code right now).

I took advantage of Highlight.js' stylesheet to inject into it also styles for BNF blocks and Game Transcripts. So, possibly, any future CSS tweaks will go there too.

I'm glad this got solved, as now both the HTML and PDF templates are starting to get into shape, and the proofreading stage is almost at the end. Hopefully, by November the Alan Manual will be production ready in both formats.

from alan-docs.