Style consistency when showing commands and their results

[panlinux]

We have a mix of:

a) show command, and in a separate code block, show the output. In this case, the command part is shown WITHOUT a leading shell prompt (i.e., like # or $ );

b) show command and output in the same code block. In this case, the the command part is shown WITH a leading shell prompt.

The argument in favor of (a) is that it's easier for people to copy the command with one click, whereas in (b) they have to select the command exactly, being careful to exclude the leading shell prompt. Going in favor of (b), though, is that it's better presented and is generally a shorter form, which doesn't need an introduction ("here is the command:", and "here is the result:").

My personal preference, visually, is (b), but it lacks a clear distinction between what is that the user has to type, and what is the result, whereas in (a) that is not an issue. Another advantage of (b) is that the leading prompt indicates whether that should be run as a regular user ($) or root (#), but I admit that is not obvious at all to first time users.

UPDATED: I hilariously mixed up my personal preference, fixed now.

[s-makin]

This is an interesting question (to which I don't have a definitive answer) - in general, in content where we'd expect people to copy/paste (tutorials/how-tos) I think it's better to have them separate (as per the styleguide), but in some explanation pages where we're not expecting people to follow along exactly, it makes just as much sense to have them all in a single block with the prompt included next to the command. That's why I don't always change them. If consistency is preferred, I'm happy to follow a stricter standard and always split them.

There is a setting in the copy-code sphinx extension that lets you specify leading prompt symbols to strip when users click the copy button. However, this only works if people use the copy button - anyone who uses highlight/copy would still get the prompt unless they're very careful, which I think is why the styleguide suggests we should avoid using prompt symbols completely. I've been removing them where it makes sense to do so, but doing so does increase the amount of text by a fair margin.