On Thu, 2 Feb 2023 at 11:32, Ciarán Ainsworth <ciaranainswo...@posteo.net> wrote: > > 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 >
Hi Ciarán, Can you please send your proposal to "doc...@freebsd.org"? Thanks for your contributions.
