From nobody Wed Feb 15 08:09:22 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 4PGrMf2Tnfz3rT5w for ; Wed, 15 Feb 2023 08:09:34 +0000 (UTC) (envelope-from carlavilla@freebsd.org) Received: from smtp.freebsd.org (smtp.freebsd.org [IPv6:2610:1c1:1:606c::24b:4]) (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-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "smtp.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4PGrMf1yR9z3rK4 for ; Wed, 15 Feb 2023 08:09:34 +0000 (UTC) (envelope-from carlavilla@freebsd.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1676448574; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=MCy5Ii28wnCgs2fbr4NoQDab3TsV+esnKpoNWzvWOU8=; b=VzUEt1LlVGzOgy8gyG2gZxSsMtn8WHBDMe4DYKeHujgUdg0e+A718cSUYmvYGSH+Z/RJR/ yXihKivZume+XoXf0k4FY2ONTIyHZRN++aRd2Qvxrmi1aQlbY1YUrdEpejmh8XP81rj5AC r2gfWqXM0gH4VsexoxKZv2Os9Njou6JIoPLzAd4vsodekZGVXMSwEaTM/qxFKOG5YJbTar RJT1WhRUunwcIrcbqqFklCUPuSV4WR73Kd8HeYJNUERZM/xQbewMpiRdVGKHBMEHVjBU/9 igVKUfIDPSA1y0yi70+aF7EuNLDWB28wW9EDSyE3fKPwDUaSKMRxedVLn1/6MQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1676448574; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=MCy5Ii28wnCgs2fbr4NoQDab3TsV+esnKpoNWzvWOU8=; b=dymqiAgf+qJphGrtn9DUc86fvnuxc41mxf9Xhe2ai/+SaQHSwvKuJzERdiFPc4/8CZceNB bT4jhlxRSBa9quSi+r7kYZTK7T4PmW97aC7F0Vol2mhi7D5A7vx2wrZkmRuRK2bIfuB0U7 OlCFBI//F/aDN5qF3++U8IB5rZLbVujZ6aF2olSPahyW7AOE2HCvXhO5gKKzp6/0BrB7G1 sTuwYHHww0PTK5az+48amyABvi3E/cgnHydVMyrVM+fS5YE/siOLQOINk8iRhj1rwByV88 DGRuGEh1xiAlme88jrJE7meN9+lZ0a2HdlOtVtnw5XhPxWOzu5aNdGgjcBacww== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1676448574; a=rsa-sha256; cv=none; b=dAYuRqMmW3y+KRF6A6NoFDzVbYcb+Db7vvEmZWErrR8jI51u579NVlVD5BNPFpJLdlj78D eLQkXcPyBfSCW07T2HOb7LsX5NQrWRg5LPVO5QZTjGv+f9yH53vPMdSa0iZbQBwTcTs1WH SkIoPOpEXxdR0jxNT23yX33T2ZNG8JCfpKu4clvifrEjp4R8BC4WsPMnlXLwxmHjzsMSSU p45Gs1ZCDBvxqyNfH0z4WvUflnOUvQ2UAH4HOBOZEYbuHlMK+5OaZLeXSS8HXTMmX664Pb iOcn8KYa8jncgX02hKPI0dMK7DscQQC79+aJovxIgVT/j18zaWMbiMf+BwbqCA== Received: from mail-oi1-f178.google.com (mail-oi1-f178.google.com [209.85.167.178]) (using TLSv1.3 with cipher TLS_AES_128_GCM_SHA256 (128/128 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (2048 bits) client-digest SHA256) (Client CN "smtp.gmail.com", Issuer "GTS CA 1D4" (verified OK)) (Authenticated sender: carlavilla) by smtp.freebsd.org (Postfix) with ESMTPSA id 4PGrMf11vLz11Lj for ; Wed, 15 Feb 2023 08:09:34 +0000 (UTC) (envelope-from carlavilla@freebsd.org) Received: by mail-oi1-f178.google.com with SMTP id bd6so15118127oib.6 for ; Wed, 15 Feb 2023 00:09:34 -0800 (PST) X-Gm-Message-State: AO0yUKX6CQxBDN8jfqEeu6ilKV51nJQqfuuONrM5CJvcLvlGeq8C7Tte YLo/l73279BjGprHZu1DYCoXkd5DAUuiIYxf4CQ= X-Google-Smtp-Source: AK7set/5pH59UWhoKU833UCTe9qCKyF0zYcxFLg9nDzD58w2JAjeV3OBOJYBbbD2A8hs/kvIPQf1yZW7IezP4VHkU94= X-Received: by 2002:a05:6808:4c2:b0:37f:59ae:4038 with SMTP id a2-20020a05680804c200b0037f59ae4038mr54402oie.125.1676448572895; Wed, 15 Feb 2023 00:09:32 -0800 (PST) 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 References: <041eb94a-7c84-9904-e4e5-280a053f159e@posteo.net> In-Reply-To: <041eb94a-7c84-9904-e4e5-280a053f159e@posteo.net> From: Sergio Carlavilla Date: Wed, 15 Feb 2023 09:09:22 +0100 X-Gmail-Original-Message-ID: Message-ID: Subject: Re: csh prompt in code blocks To: =?UTF-8?Q?Ciar=C3=A1n_Ainsworth?= Cc: freebsd-doc@freebsd.org Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable X-ThisMailContainsUnwantedMimeParts: N On Thu, 2 Feb 2023 at 11:32, Ciar=C3=A1n Ainsworth 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.