We don't want bash syntax highlighting for command-line examples, so
switch to text or, where appropriate, console.

Checklist

• make -j4 test (UNIX), or vcbuild test (Windows) passes
• documentation is changed or added
• commit message follows commit guidelines

Review requested:

• @nodejs/modules

We don't want bash syntax highlighting for command-line examples […]

That's actually untrue. We do want bash syntax for all non-console command lines.

Here's the reasoning: each single command line isn't shell-agnostic, which is what console was being used for in the past. There is no such thing as a shell-agnostic command line (unless it starts w/ node [or others and doesn't use &&, |, et al. after it], then it's up to that command's command-line argument parser to do the work), so we've chosen to go w/ Bash due to its POSIXness. I personally am not a Bash user (for my daily routine), but keeping the docs in Bash is perfectly fine. Anything else would be a mistake IMO.

We don't want bash syntax highlighting for command-line examples […]

That's actually untrue. We do want bash syntax for all non-console command lines.

My thinking was:

• We don't know that it's a bash shell. Not just csh or whatever, but a lot of these could be Windows commands.
• Seeing syntax highlighting on the command line may be confusing.

But really those are rationales probably, and I think mostly I've just seen too much misleading bash highlighting when the command prompt and output is included.

So happy to revise this to just be the one uncontroversial instance. PTAL.

a lot of these could be Windows commands

It's impossible to use git on Windows w/o first installing Git Bash.

Any dev using Windows would know this. I think we should think about the target audience here.

Well, let me correct myself, because that's not entirely true. There are other ways to do use git on Windows, but changing this to anything other than bash is more of a philosophical discussion and is way off-topic. lol

Well, let me correct myself, because that's not entirely true. There are other ways to do use git on Windows, but changing this to anything other than bash is more of a philosophical discussion and is way off-topic. lol

I certainly agree that the only logical choices (as far as I can tell) are bash or text and I'm happy to leave it as bash. My preference for text is very mild. (I don't think command lines need syntax highlighting, usually. Maybe when they get complex, but that generally should be avoided in documentation. There are other reasonable perspectives on this, though, and I'm happy to just go with bash.)

would sh accomplish the same thing? that could be a more agnostic choice, i think.

would sh accomplish the same thing? that could be a more agnostic choice, i think.

There is a point to choosing bash, which is stated above.

There is no such thing as a shell-agnostic command line

@zackschuster, the question I would have to ask is what does sh mean to you?

what does sh mean to you?

@DerekNonGeneric sh means the POSIX interface, and could be bash, zsh, csh or even just plain old sh. the argument is that representing an interface makes it a "more agnostic" reference than any particular implementation.

(this assumes sh and bash are otherwise equal wrt syntax highlighting, etc. of course 😄)

i can open a PR myself 😄

i can open a PR myself 😄

Would you?

would sh accomplish the same thing? that could be a more agnostic choice, i think.

It may be semantically more agnostic, but under the hood, I believe it is identical to bash. So the rendering will be the same.

(I'd still be in favor of such a change for semantic reasons.)

This very small change needs reviews. Other than that, it is ready to land.

PR-URL: #34837
Reviewed-By: Michaël Zasso <targos@protonmail.com>
Reviewed-By: Richard Lau <riclau@uk.ibm.com>