Editing: command tools format

Question

When I'm going to edit a Q/A, often I find that command tools such as awk, grep, sed are not highlighted or formatted in any way, even from high rep users (which could be just that they missed it).

Sometimes they are written capitalized, for example 'Sed', sometimes, as I did above, and the most common, as code: sed.

In this answer the user formatted the command as a tag: awk (which I really like).

So we have several formats:

• sed
• Sed
• sed
• sed
• SED (which I'm not sure I've seen, at least for sed, maybe for awk)

Is there a preferred format, or is it upon the user to choose one? Once I edited an answer from a high rep user formatting the command (Sed, capitalizad) as code, and they reverted that edit.

I don't want to impose my way, so I would like to know what the community thinks about this.

Answer 1

There's a great, relevant quote in this Meta SO answer:

If such a user gives one of my posts a terminal case of Lyme disease by adding twenty back-ticks then, bam, a quick rollback is all it takes to restore health.

The key point (behind the great play on words) being, of course, that excessive backticks can make a post less readable. I'm probably guilty of this in some of my answers, and I've started looking for areas where I should avoid using backticks.

That said, I'm not proposing not using inline code fences when they are warranted, but they definitely shouldn't be used in all of the cases you mention in your question.

In general, I like the answers in this Meta SO answer for guiding when to use inline code-fencing for a command:

Any string that can be recognized or generated by a computer

And from the other answer:

if something will at some point get parsed somehow (like commands, URLs, file names etc.) it is code-like in most contexts.

Given that:

• sed: When used as a command. E.g. "Run the above sed command once for each ..."

• sed: When talking about the application in a general sense. E.g. "The sed manual mentions ..."

• sed 's/foo/bar/g': The typical usage of code-fences to indicate an inline command-line (i.e. command + arguments). E.g. "You can replace every instance of foo with bar by using sed 's/foo/bar/g'."

  Side-note: I am almost always in favor of edits that add code-fencing around inline command-lines as it almost always increases readability. However, once the command-line reaches a certain length, it should often be split off to a separate code-block with triple-backticks or by indenting 4 spaces.

• Sed: According to the GNU sed manual, never correct, since the "proper noun" form isn't capitalized. It is intentionally lower-cased, apparently, and used that way even at the beginning of a sentence.

• sed: The tag format should only be used when discussing the tag or other questions related to the tag, not when discussing the command itself, IMHO. E.g. "I looked through other related sed questions, but ... ".

• AWK: When discussing the application in a general sense.

• awk: When referring to the actual command that would be entered.

• AWK: Never -- Since it is not computer-generated or parsed.

Answer 2

Some thoughts:

From the Perl documentation (perlfaq1):

What's the difference between "perl" and "Perl"?

"Perl" is the name of the language. Only the "P" is capitalized. The name of the interpreter (the program which runs the Perl script) is "perl" with a lowercase "p".

You may or may not choose to follow this usage. But never write "PERL", because perl is not an acronym.

Maybe it's just me, but I find this distinction between the language and the program useful. It might be even more useful in the case of language where there's multiple implementations, you'd still talk about the Foo language, but the implementations foo and foox could be somewhat different.

I went a step further from what the Perl FAQ says, and used code formatting for the program names, on purpose. The name of the program is also a filename on the system, a computer-readable string, so "code". Using code formatting makes the distinction between the program name and some common English word clearer, useful when you're talking about finding files with find, or cutting text files with cut.

As for other programs and languages, they seem to differ in how the names are written. AWK is an acronym, and e.g. Wikipedia consistently writes it fully capitalized, as "AWK", except when talking about the program, which they write in monospace font, a bit like code formatting here:

When written in all lowercase letters, as awk, it refers to the Unix or Plan 9 program that runs scripts written in the AWK programming language.

Then again, the manual for the GNU version of the AWK language is titled "The GNU Awk User’s Guide" with just the A capitalized, but they mostly use gawk and awk in the text, to the point of discussing "The evolution of the awk language", missing the language/implementation difference mentioned before.

Then, GNU sed is written in lowercase on the GNU pages, even at the start of a sentence. The manual does use sed or "GNU sed" in the main text, though. I don't think I've ever seen "Sed", though.

sed is commonly used to filter text, i.e., it takes text input, performs some operation [...]

I think "newer" stuff like Python and Ruby are written capitalized, and e.g. Bash's documentation consistently talks about Bash. On the other hand zsh seems to be written in lowercase on their web site, but the manual has mentions of the capitalized Zsh at some parts.

---

What does all this mean for the post author? At least that the style isn't consistent in other texts either, so it's hard to be totally wrong.

FWIW, I write Perl, Python and Bash for the languages, and would suggest to that others too.

I seem to have a harder time keeping the difference in cases like sed vs. sed where both are in lowercase, and I don't think I can write AWK/Awk/awk consistently even now. I don't really like the awk style, as I find it hard to write, and the default font for tags is much lighter than other text, so it's harder to read, too.

I don't think it's easy to write a hard recommendation though, since the customs do vary.

Answer 3

This is one of those bikeshed problems. As I said before on several ocasions, only use it when you expect the user to copy and paste verbatim something non-trivial. So, no sed, definitively not sed (unless you are linking the user to the site sed tag) and prefer lower-casing whenever possible.