Date: Wed, 15 Feb 2023 09:09:22 +0100 From: Sergio Carlavilla <carlavilla@freebsd.org> To: =?UTF-8?Q?Ciar=C3=A1n_Ainsworth?= <ciaranainsworth@posteo.net> Cc: freebsd-doc@freebsd.org Subject: Re: csh prompt in code blocks Message-ID: <CAFwocyPkU5pHUKzwFqCzWe6gvHR36pCoJ_KN1pm=VQD1UsyDrQ@mail.gmail.com> In-Reply-To: <041eb94a-7c84-9904-e4e5-280a053f159e@posteo.net> References: <041eb94a-7c84-9904-e4e5-280a053f159e@posteo.net>
next in thread | previous in thread | raw e-mail | index | archive | help
On Thu, 2 Feb 2023 at 11:32, Ciar=C3=A1n Ainsworth <ciaranainsworth@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=3D" 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=3D%". 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=C3=A1n Ainsworth > > [1]: https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=3D269243 > [2]: https://docs.freebsd.org/en/articles/linux-users/#shells > Hi Ciar=C3=A1n, Can you please send your proposal to "doceng@FreeBSD.org"? Thanks for your contributions.
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?CAFwocyPkU5pHUKzwFqCzWe6gvHR36pCoJ_KN1pm=VQD1UsyDrQ>