Enhance Hugo Syntax Definitions and Examples

[tajmone]

• POSTPONED — This enhancement is postponed after the 1st release of the book.
• UNCOFIRMED — Still needs testing and evaluation before giving the green light.

Hugo Syntax definitions are not syntax highlighted, they are just literal blocks (see #35) with a custom role (literal, role="hugosyntax") to allow custom styling via CSS (or other means, in different output formats).

The block is styled using the Base2Tone Lake colour scheme by Bram de Haan, which provides 4 base hues available in eight tints variations. Currently we are using just two colours: background and foreground.

We could enhance Hugo syntax definitions by using different colours for keywords, parameters. comments and surrounding code, as well as the various token indicating optionality ([]), alternatives (|) and omissions (...).

But this would require manual implementation by using a combination of bold, italic and custom styles via the [style]#text# notation — or even exploiting classes on bold and italics via the [.style]*text* notation (See §10.5.6. Role » Inline Assignment in Asciidoctor Manual).

It's important here to think carefully on how the document will be rendered by other people targeting different formats or using different templates. The final document must look nice independently of the template and stylesheet employed. Therefore, it's better to use a styling notation that would not affect the visual appearance of the document in other toolchains, but at the same time use a system that allows to enforce these intended styles also across other formats and backends.

Possibly, using bold for styling the keywords that are central to the syntax definition (or syntax example) should be acceptable for it would always provide an acceptable styling across al formats and templates.

As for customization of the additional symbols for optionality, etc., it might be wiser to use custom roles that would not affect visually those elements in non-dedicate templates, just to be on the safe side.

I need to experiment with this first.