bat
bat copied to clipboard
sharkdp
Explanation of project confuses
Describe the bug you encountered: Searching projects written on rust. I checked this project and thinking to understand what it is and what it does.
About
A cat(1) clone with wings.
...
What did you expect to happen instead? Proper explanation, my mind is full of cute gophers, crabs, bats, and now cats? No Cat is not a pet, animal, instead it is a unix tool that reads file and writes to standard output. So explanation should reflect this.
About
Bat is a command that reads file and writes elegantly to standard output. Aka a cat clone with wings.
...
How did you install bat?
Not installed.
bat is cat with some fancy extras like line numbers and syntax highlighting
A cat(1) clone with wings.
That's not the explanation of our project. It's not even a short description. It's a slogan, and I'd like to keep it.
The (1) suffix to "cat" is not an accident either. cat(1) is a typical UNIX-style reference to a man page. The number in parenthesis stands for the man page section where 1 specifically stands for "General commands". So for those with a UNIX background, it should be clear that cat(1) refers to the GNU coreutil cat, the command.
Now that being said, I still think that the documentation could be improved. And I agree with you that we should probably have a better first-line description of the man page that could be put into the README and/or the man page.
In both readme and man we have
A cat(1) clone with syntax highlighting and Git integration.
which seems like a good one-line description to me. What is the problem with that description? That it assumes people know what cat is? I don't think that's a problem, because people that don't know cat are unlikely to want to use bat.
