DEV Community

Cover image for Reading The Fancy Manual: Documentation in Bash

Reading The Fancy Manual: Documentation in Bash

ddhogan profile image Donna Hogan ・1 min read

Good afternoon quaranteam! I have a Sunday afternoon coffee question:

To read documentation for a command, such as ls in Bash in macOS, we use man ls, but in Linux we use ls --help (or ls -h).
Both macOS and Linux are built on Unix, so...

What accounts for this difference in the way we access documentation?
What other subtle differences do you think a beginner should be aware of?

Discussion (4)

Editor guide
ghost profile image

man is also used in Linux and BSD; usually --help is a cheatsheet with the usage man is commonly more detailed, of course it depends on the specific program, but man is definitely also available in Linux. Some very lightweight distros may not include man pages in their base system to save space, of course docker images often do this for obvious reasons, but most distros include man pages by default.

By the way MacOS in ancient times used FreeBSD code, nowadays I don't think has much of it; all BSD came from an older version of UNIX, so they are like cousins of UNIX, MacOS would be a distant relative that has almost nothing in common, Linux is "inspired" by UNIX, similar structure, common standard ABI and some ideas, but not actual code of UNIX, at all.

Another difference is that Linux is more distributed in it's development, technically only the kernel is called Linux, (I find that to correct someone about that is kinda pedantic); but in this case is relevant. The "Linux" dev team is in fact the kernel team lead by Torvalds and they only take care and distribute the kernel, BSD flavors are different, they take care of the whole "base system" that includes the kernel but also the main tools.

Also important not to confuse Linux distros with BSD "flavors", Linux distros are more of a distribution in a logistical sense, is what they ship and bundle; OpenBSD, in contrast, has very little to do with FreeBSD for example, they don't share much code, they don't even use the same kernel AFAIK, that's why they even support different HW and filesystems.

On a side-note, Linux man pages are good, sometimes great; OpenBSD man pages are glorious, magnificent, nothing shy of a chapter of a well written book and a program without a well written man page is not accepted in the base sysyem. No experience with MacOS whatsoever.

ddhogan profile image
Donna Hogan Author

Thank you for the explanation robertorojasr!
I wonder if BSD has any equivalent --help cheatsheet (either built-in or 3rd party)?

ghost profile image

yea, same thing, in general having a --help is just a good practice for any CLI program, if you think about it, those are the "original" UI, since even before the internet, imagine a program without a --help, is useless, every parameter not mentioned in --help is like it doesn't exist, how would you know that -sh in ls do something?, no internet, no help menu, no web documentations, no github, where else do you document a program?, where do you explain what a program do and how?. In that sense OpenBSD got it right, a CLI program, any program in tha matter, shouldn't assume the existence of internet, should be self-contained, self-documented. From our "modern" POV man pages and --help is some "bonus" or even unnecessary thing but without internet they become essential. And even the only way for a programmer to communicate with the user.

bu profile image
Burak Sümer

As far as my knowledge, man is available in GNU/Linux as well. I used it all the time when I had no access to the internet. It was the way to learn and solve problems for me.