Starting a sentence with the name of a program or command-line tool: capitalization?
Say you want to talk about a piece of command-line software, like make or bash or the cp command. These commands are all lower-case, and case-sensitive (i.e. won't work on the computer if you capitalize them), and also often double as the names of the software projects that write the programs that the commands invoke. What happens when you want to start a sentence with the name of one of these tools? Which of the following is best?
- cat is a Unix utility for concatenating files. (Start a sentence with a lower-case letter, which looks weird.)
- Cat is a Unix utility for concatenating files. (Capitalize the command name, which looks weird and won't run.)
-
catis a Unix utility for concatenating files. (Start the sentence with one of these weird code box things. Requires that that formatting option be available, and you still end up leading with a lower-case letter.) - One Unix utility for concatenating files is cat. (Just write around the problem because you don't know what to do otherwise.)
Do any style guides address this issue?
This post was sourced from https://writers.stackexchange.com/q/23419. It is licensed under CC BY-SA 3.0.
2 answers
You are accessing this answer with a direct link, so it's being shown above all other answers regardless of its score. You can return to the normal view.
Rule #1 in technical documentation is: don't mislead the reader. If the command or function name begins with a lowercase letter, capitalizing it is an error -- it's not "Cat" but "cat". The Microsoft Manual of Style specifies that literal elements like this should be written with their correct case. It also calls for using text styling to offset them, as do other style guides I've used. (Microsoft favors bold; others favor monospace.)
Surprisingly, software-oriented style guides in my experience don't address the specific case of beginning a sentence with these items. If you can write around the problem without making the documentation more cumbersome, I've found it's best to do that. Instead of
catis a Unix utility for concatenating files.
You might be able to write
Use
catto concatenate files.
You could write
The
catutility concatenates files.
However, this can quickly become either cumbersome or inconsistent -- if you say "the cat utility" in some places but "cat" in other places, you leave readers wondering why. But if you use the former formation everywhere, you make the documentation harder to scan and add extra words seemingly needlessly.
The software-documentation teams I've been part of for the last 20 years or so have all followed this guideline: write around the problem if you can do so reasonably, and if you can't, just start the sentence with the lowercase name. Using text styling for command/function/etc names mitigates the capitalization "error".
0 comment threads
The GNU site itself treats the name of the Make utility as an uppercased word: https://www.gnu.org/software/make/
There does seem to be a convention to frequently use make (the command) where Make (the name) would seem more appropriate. The GNU Make manual seems to do this almost exclusively (https://www.gnu.org/software/make/manual/make.html) but always with a font change to indicate that it is the command that is being used.
So those examples would justify the second and third options for Make, though the manual seems to avoid using make at the beginning of a sentence.
It is less clear that cp or cat can be treated this way, though. They are commands more than stand-alone products like Make. I'd be inclined to avoid using them as stand alone names and instead use "The cat command" as in:
The
catcommand is used to concatenate files.
0 comment threads
0 comment threads