Date: Thu, 2 Feb 2023 10:31:51 +0000 From: =?UTF-8?Q?Ciar=C3=A1n_Ainsworth?= <ciaranainsworth@posteo.net> To: freebsd-doc@freebsd.org Subject: csh prompt in code blocks Message-ID: <041eb94a-7c84-9904-e4e5-280a053f159e@posteo.net>
next in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?041eb94a-7c84-9904-e4e5-280a053f159e>