Author's Guide: Switch to Highlight
tajmone opened this issue · comments
Currently the are no impediments for not using Highlight for the Alan Author's Guide, for it doesn't it uses callouts anywhere (these being what prevents using Highlight with Asciidoctor — See #36 on this).
So, since this book is still in the making, the question really boils down to whether we are planning to use callouts or not in it! Callouts are indeed a cool feature, especially in these type of documents which contain lots of code examples, for they introduce a nice notes-like system for source code.
Eventually, the Highlight extension will support callouts, but right now it doesn't. Should we just keep using Highlight.js, and enjoy callouts? Or should we rather switch to Highlight and postpone using callouts in the book until they are supported?
It's a matter of choosing which one should get the priority: the highlighter toolchain or the callouts feature?
Since this is Thomas's book, the choise belongs to him really...
IMPORTANT! — See also proposal #107 to switch to Rouge instead!
So, what are the drawbacks of using Highlight.js? From your comments I presume there are some.
So, what are the drawbacks of using Highlight.js?
I prefer Highlight for various reasons, the main one being that syntax highlighting is done during the conversion stage, so no JavaScript is actually needed in the final document.
There are means to achieve this also with highlight.js, but it involves additional Asciidoctor extensions and using the Node.js version of Asciidoctor instead of Ruby.
Also, the Alan syntax for Highlight is more polished and I find it easier to work with Highlight syntaxes in general.
Last but not least, Highlight supports many other output formats beside HTML, so it might be useful for other ebook types too.
But, at the end of the day, both highlighters do their job well, but I'd prefer to use only one to avoid having to maintain multiple stylesheets in Sass. Right now the Beginner's Guide is the only document using Highlight, so in a way I've already placed my self in the double-standard situation.
If only I managed to write that Asciidoctor extension for Highlight, using the new API, then Highlight would support call-outs too. I really like call-outs, and the thought of having to do without them really annoys me. But my knowledge of Ruby is too weak for that task, for I can't figure out how to interface to the Asciidoctor API, even after having gone through the code multiple times.
Rouge Unsupported!
Unfortunately, this document will also have to use Highlight instead of Rouge, because it uses highlight marking inside code blocks, which is currently not supported with Rouge.
This means you won't be able to use callouts (not in highlighted code blocks, at least).
I've added thin info in its README, an tweaked the build script to use Highlight instead of highlight.js.