Switch from Highlight to Rouge

[tajmone]

We should stop using Highlight and switch to Rouge instead, following the steps of the ALAN Docs and ALAN i18n repositories. Our custom ALAN syntax (lexer) for Rouge is production ready, so are the Sass stylesheets.

• Add ALAN Rouge assets to repository:
  • In _assets/adoc/:
    • Add ALAN Lexer & custom Rouge adapter.
    • Delete:
      • highlight-treeprocessor_mod.rb.
      • haml/ folder (no longer needed).
    • Update README accordingly.
  • Sass/CSS — In _assets_src/sass/:
    • Substitute Highlight themes with Rouge themes.
      • or delete the whole folder if we decide to reuse the docinfo.html from ALAN Docs!
    • Generate/update _assets/adoc/docinfo.html.
      • or should we just include the generated docinfo.html from ALAN Docs?
• Asciidoctor:
  • Update all ADoc build scripts to use Rouge instead of Highlight.
  • Remove from source docs highlighter attributes referring to Highlight.
  • Either add Rouge settings to source headers or just in build script.

SASS NOTE — I need to look into the Sass sources and decide whether it's worth to keep our own sources here or just re-use the standard CSS from ALAN Docs.

The obvious advantages of reusing the same CSS from ALAN Docs is that we reduce maintenance work. We could just add a script that downloads via cURL the raw docinfo.html file from ALAN Docs, replacing our version with its latest.

IRC, our Sass sources contain a couple of extra styles for transcripts (e.g. using STRONG for player commands, to make them red, and styling for comments), but we could then add these to the Sass sources on ALAN-Docs, to make them available to us and any other document therein (they're optional styles, so it should be fine to add them).

But I need to verify that we don't use different colour schemes for ALAN code, and that we're OK to reuse the same standard themes from ALAN Docs — i.e. if we prefer to use different colours in our themes we should then keep our own Sass sources in the repository.

The pros and cons of having to maintain separate Sass/CSS styles need to weighed carefully, for they add quite some extra work. Also, if all ALAN related documents use the same stylesheets, it's going to be easier to build all the documents using a common toolchain (e.g. in the future we might be also building the StdLib Manual on ALAN Docs, if this is going to simplify things, and maybe only generated an amalmagamated single AsciiDoc file here).

References

• alan-if/alan-docs#107 — Switching to the Rouge Highlighter

[AnssiR66]

I think that's good for integrity, we can go ahead accordingly.

[tajmone]

Thanks!

BTW ... Please enable "Discussions" in the repository settings, so we can move all those Issues which are mere considerations (as opposed to practical TODO tasks) therein and keep Issues uncluttered. Also, Discussions is a very cool feature for it allows us to freely discuss any topic without feat of polluting an Issue or going off topic!

[tajmone]

A Few Considerations on Sass

I'm still not sure about dropping our custom Sass stylesheets, the reason being that the new ALAN syntax for Rouge covers many more syntax elements than Highlight did, but on the ALAN Docs repository we're hiding these new elements by colouring them alike, i.e. in order to mimic the old Highlight theme (it's Thomas desire to keep the colours down to a minimum). But I think that here we could experiment with some advanced themes which would benefit from the new elements (e.g. strings delimiters having their own colour, etc.).

Definitely, we need to ensure that any documents from this project will build correctly if used on the ALAN Doc toolchain — i.e. any custom styles must be present in the stylesheets and template available there — but this doesn't mean that those style need to be implemented identically here, they just need to be compatible (after all, the whole idea in AsciiDoc is to separate formatting and styling concerns, allowing freedom of variations).

But surely, in the initial stage after switching to Rouge I'll be using the docinfo.html file from the ALAN Docs repository. But I suggest keeping the old Sass sources (mentioning they are not being used) until we've experimented further.

Also, it's worth noting that currently Asciidoctor doesn't support span styles in Rouge (since Rouge is natively part of Asciidoctor, we can't do much except wait for the fix from upstream).

Rouge Limits

Currently Rouge can't handle highlight/marked and spans formatting — if these are found, the block is simply not highlighted.

I don't think we're using these formatting styles in our code blocks, but we should check, and if we are we'll have to adopt and alternative solution.

Rouge Benefits

With Rouge we can finally use callouts in our documents!

This will make any examples in the documentation easier to understand.

We can even add callouts in the StdLib sources, in case of code snippets being reproduces in the StdLib Manual (or other docs), since these can be stripped from the final distribution package via the sanitation scripts, along with the region-tag comments (which we're already using to mark snippets that need to be include::d in the docs).

Also, these comments could make the code more readable for us maintainers, since we'll be working on the un-sanitized library sources.

Transcripts Styles

We'll need to add our extra custom transcript styles to the ALAN Docs Sass sources (if they aren't there already, which they might, I need to check).

We're using SED to carry out some AsciiDoc transformation on the generated transcripts: player commands are rendered in bold, and comments are styled via #[comment]..#, and other minor formatting tricks.

These styles are on Example blocks with custom roles/classes.

For more info see Toolchain Details.

[AnssiR66]

Ok Tristano, can you please advise about the exact path about enabling "discussions" in the settings, as I cannot find it right away. Thanks!

[tajmone]

It's in the main settings page, down below. It's just a checkbox with "Enable Discussions" — there's also a "Setup Discussions" button, but you can skip that since it just creates a default welcome page, which we don't really need.

[AnssiR66]

Tristano, let me know if I have managed to enable discussions or, if not, what is the exact procedure I need to take. Thanks!

[tajmone]

Tristano, let me know if I have managed to enable discussions

You have! Thanks.

Now I'll begin converting to Discussions various Issues which are more conversations and thoughts exchanges than practical TODO stuff; so we'll have less cluttering here on Issues- Old links to Issues are preserved, for the Issues are copied to Discussion and given a new ID number, and the old one preserved with an auto-generated notice (or redirection, I don't remember) pointing to the new Discussion.

[tajmone]

Opted# Opted to Reuse Styles from ALAN Docs

@AnssiR66, in the end I've decided to drop the Sass folder here, and instead add our custom styles to the Sass sources in ALAN Docs, so we can just import the pre-built docinfo file for the StdLib docs.

Since the ALAN Docs repository is the main reference for all the Rouge related assets (the ALAN lexer, the docinfo styles, etc.) I've just added in the new _assets/rouge/ folder a bash script (fetch-latest.sh) which takes care of downloading the latest version of all assets from the ALAN Docs repository via cURL. So updating these assets is a one-click operation.

I think that we should strive to centralize as many assets as possible in a single repository, and reuses them in all other repositories, so we can avoid duplicate work across projects. After all, the ALAN Docs project is the main documentation reference, so it's easier to add new styles we might need there, and then import them here.