Communities

Writing
Writing
Codidact Meta
Codidact Meta
The Great Outdoors
The Great Outdoors
Photography & Video
Photography & Video
Scientific Speculation
Scientific Speculation
Cooking
Cooking
Electrical Engineering
Electrical Engineering
Judaism
Judaism
Languages & Linguistics
Languages & Linguistics
Software Development
Software Development
Mathematics
Mathematics
Christianity
Christianity
Code Golf
Code Golf
Music
Music
Physics
Physics
Linux Systems
Linux Systems
Power Users
Power Users
Tabletop RPGs
Tabletop RPGs
Community Proposals
Community Proposals
tag:snake search within a tag
answers:0 unanswered questions
user:xxxx search by author id
score:0.5 posts with 0.5+ score
"snake oil" exact phrase
votes:4 posts with 4+ votes
created:<1w created < 1 week ago
post_type:xxxx type of post
Search help
Notifications
Mark all as read See all your notifications »
Q&A

Starting a sentence with the name of a program or command-line tool: capitalization?

+1
−0

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.)
  • cat is 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?

History
Why does this post require moderator attention?
You might want to add some details to your flag.
Why should this post be closed?

This post was sourced from https://writers.stackexchange.com/q/23419. It is licensed under CC BY-SA 3.0.

0 comment threads

2 answers

+0
−0

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 cat command is used to concatenate files.

History
Why does this post require moderator attention?
You might want to add some details to your flag.

0 comment threads

+0
−0

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

cat is a Unix utility for concatenating files.

You might be able to write

Use cat to concatenate files.

You could write

The cat utility 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".

History
Why does this post require moderator attention?
You might want to add some details to your flag.

0 comment threads

Sign up to answer this question »