Man pages are intended to be an exhaustive description of the individual options, switches and command arguments and what they do; but they won't tell you how to combine those to be useful in your particular case. It's up to you to figure that out.
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.
> Man pages are intended to be an exhaustive description of the individual options, switches and command arguments and what they do; but they won't tell you how to combine those to be useful in your particular case. It's up to you to figure that out.
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".
I frequently use TLDR, and I wouldn't describe it as an incantation. It's for the case where, say, I know there's a grep flag for inverse match or case-insensitive, but don't use it often enough to remember it. It surfaces the (community-driven) top use cases, and it's pretty clear from the context what the flags are doing. (As seen here: https://github.com/tldr-pages/tldr/blob/master/pages/common/... ) If I don't see my use-case in tldr I'll move on to the man page.
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. ;-)
On OpenBSD (and other systems using mandoc as the default “man” program), I can jump to an unknown flag right away with the pager’s tag support: “:tv”
-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.
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.