Typical man pages are well, like learning a language by studying a dictionary, alphabetically. It may contain all information, but a clear F on UX. Some packages get slightly better with starting from the most common use cases, with examples (and digestible errors).
However, I would be even more interested to see what is the actual usage pattern (e.g. from .bash_history / .zsh_history). Do you know any datasets with longer such?
What I find annoying is the number of command line programs that don't even have man pages anymore. Or maybe that's just an artifact of installing them with brew?
What I find interesting is that for the most part (there are exceptions), the older the man page, the more useful it is. Realistic examples. Succinct descriptions. User-friendly terminology. Too many of the newer man pages seem inflated and full of jargon to make themselves seem important or worthy.
Ubuntu pull most of its packages from Debian, and Debian Policy says that every package that provides binaries should provide manpages for them as well. It is not a hard requirement but their absence is considered a bug.
A messed-up MANPATH environment variable can also cause man pages to not be found. In ‘man’ used on many flavors of Linux, MANPATH behaves differently from, say, PATH: an empty colon-delimited section means something like “use the system’s regular ‘man’ configuration for finding man pages”. Without that, it seems like a bad MANPATH setting will cause default mannpages not to be found.
It's simply a lot harder to explain things in simple language, so I'd hesitate to ascribe such intent.
One of the best things that ever happened in my career was having a desk across from the entire SunOS manual set. I'd pull them down one at a time and read them, cover to cover. It paid off, big time, and I strongly recommend it.
One day I saw “type ‘man man’” and “apropos” written on a chalk board.
That is how I learned Unix.
* https://unix.stackexchange.com/a/448799/5132
There was also "learn", in BSD as I recall.
tldr caters to an entirely different heuristic: I have this use case, give me a list of use cases and the corresponding combination of switches, options and arguments for each respective use case. tldr won't explain to you what each individual switch, option or argument does, turning the provided commands into black boxes.
Here's the trade off:
The former has a steep learning curve and figuring out how a tool works doesn't solve your immediate problem. But if you commit the meaning of switches, options and arguments for common tools such as awk, sed, tar, ls,... to memory, you will become proficient at solving any problem with a few tools over time.
The latter has a low learning curve and you just have to copy/paste a command to solve your problem. But tldr won't tell you how those switches and options work. And you will just use them as incantations that magically help you to solve a limited number of cases. If you end up with a use case that isn't listed, you are left in the dark as far as tldr is concerned.
So, is tldr a bad tool then? No! If you are confronted with the command line sparingly, then tldr helps to lower the bar and solve your immediate problem. But if you hope to grow into a proficient shell user, then you're still going to have to grok the man pages one switch, option and argument at a time.
I'm a polyglot. Studying a language by opening a dictionary and starting alphabetically, is arguably, the worst way to get there. You would start with learning a set of common words and basic grammatical rules, and then expand over time through practice and instruction: speaking, reading and writing.
The same applies to command line tools and man pages: they are reference materials first and foremost.
OTOH, sometimes I'll copy-paste some perl or awk dark magic from Stack Overflow, and then try modify it piecemeal to fit my case. That's an incantation :)
I think that largely depends on who's using the tools and how acquainted they are with command line tools. An absolute beginner likely will not know what tar's 'f' flag does, or assume something else.
> OTOH, sometimes I'll copy-paste some perl or awk dark magic from Stack Overflow, and then try modify it piecemeal to fit my case. That's an incantation :)
And I absolutely have no qualms doing the same when push comes to shove. Ain't nobody always got the time. ;-)
x - extract | f - file | z - operating on tar.gz or similar.
Edit: v - verbose
-v Verbose operation mode. If -v is specified multiple times or if
the -t option is also specified, tar will use a long format for
listing files, similar to ls(1) -l.
Man pages for newer tools, like all of the lvm utilities, include examples at the end.
I would like to see it similar to what powershell has with their examples built into the documentation.
No, thankfully.
Try `man man | col -b | grep EXAMPLES`
(As an example, grep was finding EX but not EXA. Man told me I could pipe to col -b to strip formatting, hinting the issue might be special characters. This was quite helpful of them, even if it isn't strictly "man's responsibility".