Move relevant sh codeblocks to console

[mkatychev]

yeah so my stance on that is that writing into a console is not normally syntax highlighted either, so it matches.

If we have a shell script, or a bash script, then it makes sense to use those, but my stance here is that if it's a console command you're supposed to enter there are other ways to make it more readable:

something \
    --like this \
    --rather-than console

and if it's code, then it should be highlighted.

Originally posted by @vados-cosmonic in #218 (comment)

[itowlson]

It would be useful to have an example of what difference this would make to the rendered output. (I'm not sure if I need to address this comment to Victor or Mikhail though, sorry!)

[mkatychev]

This should be sent to @vados-cosmonic, I just split his #218 (comment) into a separate PR

[vados-cosmonic]

Hey @mkatychev thanks for filing this issue -- to recap context for @itowlson (please correct me if I'm wrong).

• Mikhail noted that we would lose syntax highlighting for a block that was sh
• I noted that things that are entered into the console are usually not highlighted to begin with, and that sh/bash/etc where more for scripts than for things you enter at the console (the quote above), IMO

I think Mikhail took this as a good chance to go around the codebase and make the change with that philosophy in mind (thanks!), but I asked for a issue that we could discuss this, since I think it could be a point of contention.

I'm happy to change my stance on this, but to sum up:

• console for things people should paste in
• sh/bash/etc for actual scripts (that people should copy into a file and run)
• <lang> for code snippets

I personally like the style of demarcating commands and the output people should see in prose, but that's somewhat separate!

[mkatychev]

Happy to move the related PR into draft of this is contentious. This seemed to be a simpler lift than doing it in just the Rust file creating more inconsistency.

[vados-cosmonic]

Sorry I think I should have been clearer -- I was thinking that before we go make the whole codebase one way or another, we should probably get input/discuss it first!

I think once people have put in some input we can figure out how to proceed? Then we'll know for the future/can avoid having to actively make the decision again if someone else contributes.

[itowlson]

@vados-cosmonic Can you give examples of how this affects the render though? Taxonomy thrills my librarian heart, but my tech author head wants clarity on what readers will see.

[t3hmrman]

Ahh so it looks something like this (this was the line in question with the comment):

(console)

cargo component build --release

(sh)

cargo component build --release

It really depends on what is in there of course (and what rules sh/bash might apply), but here's a longer example:

(console)

mkdir -p deps/docs
cp adder/target/wasm32-wasip1/release/adder.wasm deps/docs/adder-impl.wasm
cp calculator/target/wasm32-wasip1/release/calculator.wasm deps/docs/calculator-impl.wasm
cp command/target/wasm32-wasip1/release/command.wasm deps/docs/command-impl.wasm

(sh)

mkdir -p deps/docs
cp adder/target/wasm32-wasip1/release/adder.wasm deps/docs/adder-impl.wasm
cp calculator/target/wasm32-wasip1/release/calculator.wasm deps/docs/calculator-impl.wasm
cp command/target/wasm32-wasip1/release/command.wasm deps/docs/command-impl.wasm

[itowlson]

@t3hmrman Thanks! If it's just changing it between blue and black then my inclination is to do nothing because it will be a lot of policing for no real reader impact. But if other folks feel more strongly then I'm happy to go along with whatever.