From nobody Thu Feb 2 10:31:51 2023 X-Original-To: freebsd-doc@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4P6w7v70jfz3cqWc for ; Thu, 2 Feb 2023 10:31:55 +0000 (UTC) (envelope-from ciaranainsworth@posteo.net) Received: from mout02.posteo.de (mout02.posteo.de [185.67.36.66]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 4P6w7t3zPxz41sP for ; Thu, 2 Feb 2023 10:31:54 +0000 (UTC) (envelope-from ciaranainsworth@posteo.net) Authentication-Results: mx1.freebsd.org; dkim=pass header.d=posteo.net header.s=2017 header.b=gb0jJMGY; spf=pass (mx1.freebsd.org: domain of ciaranainsworth@posteo.net designates 185.67.36.66 as permitted sender) smtp.mailfrom=ciaranainsworth@posteo.net; dmarc=pass (policy=none) header.from=posteo.net Received: from submission (posteo.de [185.67.36.169]) by mout02.posteo.de (Postfix) with ESMTPS id 349BE2406C2 for ; Thu, 2 Feb 2023 11:31:52 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=posteo.net; s=2017; t=1675333912; bh=7jI90wy/3NEumfHcO2Irwdy88LpoY44/Raq4luhKf9Q=; h=Date:To:From:Subject:From; b=gb0jJMGYsV1dbdldX4fBIdVDpy/liTSW7v5APkeKJpdIy6JsHJDpTJa6a130FH7ag QvDzj2oXolQsMn2dsId1ABioqotIophBAi8Hp1mHYSGivrEG0EnDzewyTS8OJCF45Y HJ8bIUBLRbQgXvmdEnk7F7GrIWHqcqY0NxeFpZP00XSIVVHVfjszu+OOjvB5EmcD49 P6dbb0e0Co3xKTJ2B9OkT9B/1VLxYPCkxaGab3Uocr/JCPxINEc/b4plIA/O9VAjM8 +YYxE1u1Z6z1qV1pZhFz8EIa8JGdsFEGengo/TwdTXUDUPcALNj60VH6ogF3kUCayU Mkeu6ZL1T5JCg== Received: from customer (localhost [127.0.0.1]) by submission (posteo.de) with ESMTPSA id 4P6w7q5z5tz6tmH for ; Thu, 2 Feb 2023 11:31:51 +0100 (CET) Message-ID: <041eb94a-7c84-9904-e4e5-280a053f159e@posteo.net> Date: Thu, 2 Feb 2023 10:31:51 +0000 List-Id: Documentation project List-Archive: https://lists.freebsd.org/archives/freebsd-doc List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-freebsd-doc@freebsd.org MIME-Version: 1.0 To: freebsd-doc@freebsd.org Content-Language: en-US From: =?UTF-8?Q?Ciar=C3=A1n_Ainsworth?= Subject: csh prompt in code blocks Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 8bit X-Spamd-Result: default: False [-3.99 / 15.00]; NEURAL_HAM_MEDIUM(-1.00)[-1.000]; NEURAL_HAM_LONG(-1.00)[-1.000]; NEURAL_HAM_SHORT(-1.00)[-1.000]; R_MIXED_CHARSET(0.71)[subject]; DMARC_POLICY_ALLOW(-0.50)[posteo.net,none]; RCVD_DKIM_ARC_DNSWL_MED(-0.50)[]; R_DKIM_ALLOW(-0.20)[posteo.net:s=2017]; RCVD_IN_DNSWL_MED(-0.20)[185.67.36.66:from]; R_SPF_ALLOW(-0.20)[+ip4:185.67.36.0/23]; MIME_GOOD(-0.10)[text/plain]; FROM_HAS_DN(0.00)[]; TO_MATCH_ENVRCPT_ALL(0.00)[]; MLMMJ_DEST(0.00)[freebsd-doc@freebsd.org]; PREVIOUSLY_DELIVERED(0.00)[freebsd-doc@freebsd.org]; RCPT_COUNT_ONE(0.00)[1]; RCVD_VIA_SMTP_AUTH(0.00)[]; ASN(0.00)[asn:8495, ipnet:185.67.36.0/23, country:DE]; MID_RHS_MATCH_FROM(0.00)[]; RCVD_COUNT_THREE(0.00)[3]; TO_DN_NONE(0.00)[]; ARC_NA(0.00)[]; DKIM_TRACE(0.00)[posteo.net:+]; MIME_TRACE(0.00)[0:+]; FROM_EQ_ENVFROM(0.00)[]; RWL_MAILSPIKE_POSSIBLE(0.00)[185.67.36.66:from]; RCVD_TLS_ALL(0.00)[] X-Rspamd-Queue-Id: 4P6w7t3zPxz41sP X-Spamd-Bar: --- X-ThisMailContainsUnwantedMimeParts: N 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