Hi everyone,
Off the back of a ticket I raised[1] I've been looking into the
documentation for the syntax highlighter we use (Rouge) and have noted
that we should probably start using the console lexer rather than the
shell lexer as using shell is treating console blocks as scripts and
breaking syntax highlighting when it encounters a single or double quote.
The console lexer recognizes the following characters as prompts by
default: $,#,>,;. You can specify a different prompt by using the
override "?prompt=" with a comma-separated list of strings you want to
use as prompts. In theory, this would allow us to simply update
everything with "?prompt=%". However, the lexer isn't particularly
smart, and is liable to treat all occurrences of the prompt character as
a new prompt. This means that if we have an output that mentions, for
example, a completion percentage, it breaks.
I raised the question in IRC about the use of the "%" for the prompt.
From my understanding, this is a csh/zsh convention. We use this prompt
to denote a user-level shell, and "#" denote a root shell. From our own
documentation[2], we note that sh is the "default" shell. I would go
further and postulate that the majority of users will use sh (default),
bash (Linux converts), ksh (OpenBSD converts), or fish. All of these use
"$" rather than "%" by default. The exception to this would be zsh,
which is definitely picking up in popularity. But given that we can only
choose one, I would argue that the happy path is to assume sh for a
standard user prompt since it's the first suggestion when using adduser
on a new system, and is our documented "default".
I wanted to see if there is any appetite at all for changing this prompt
in the documentation examples? I can see the following advantages to
changing it:
1. It makes using the console lexer for syntax highlighting much easier
2. It is arguably familiar to a greater number of users than "%" due to
its prevalence in Linux and OpenBSD documentation
The alternative would be to patch in support for a "%" prompt in Rouge
so that we can use the console lexer as-is, without having to worry
about broken highlighting or additional settings.
Please let me know your thoughts. I'm still pretty new to this, so it's
entirely possible I've missed a discussion where this was decided-upon
previously.
Ciarán Ainsworth
[1]: https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=269243
[2]: https://docs.freebsd.org/en/articles/linux-users/#shells
