csh prompt in code blocks

From: Ciarán_Ainsworth <ciaranainsworth_at_posteo.net>
Date: Thu, 02 Feb 2023 10:31:51 UTC
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 

Ciarán Ainsworth

[1]: https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=269243
[2]: https://docs.freebsd.org/en/articles/linux-users/#shells