Command line documentation style guide

[stevepiercy]

Question

Should we retain or remove command prompts from our documentation?

Current practice

Typographical Conventions specifies our current practice, using command prompts to denote that we are using either a *nix-based OS ($) or a Windows OS (c:>\). Code block examples exist as reference for *nix and Windows. In our tutorials where most of the commands appear, we state that we use the *nix version of commands:

Commands in this tutorial use UNIX syntax and paths. Windows users should adjust commands accordingly.

And we use headings or similar indicator preceding the commands, but we could do a little better.

Issues

This has a few unintended consequences.

• PowerShell is the new default shell in Windows 10 and later.
• Syntax highlighting for the Pygments lexer doscon is poor.
• Syntax highlighting will fail for the Pygments lexer powershell when a command prompt is used in the code block.
• *nix shell prompts are ignored.
• Command prompts are superfluous and get in the way of copy pasting.

Proposal

The proposal is to do the following:

• Precede sections of commands with a heading or similar clear statement in which OS the command should be run.
• Remove command prompts from code-blocks.

See also #2880

[stevepiercy]

Closed by #3330