Man pages are really already TLDR pages. They suck for introductory documentation (most times) but are really useful if you just can't quite remember the switch or its parameters.
I don't know what niche this is supposed to fill?
I don't know what niche this is supposed to fill?
They list all possible ways of controlling the program. Have you seen the man page for curl? http://man.cx/curl
If we accept that man pages shouldn't be less than a manual, how then to deliver the top n recipes that demonstrate how the program can be used in the majority of cases?
In the case of curl, it's really just a GET, a JSON POST, a file upload... and perhaps add in an auth header or non-standard header.
Example: http://stackoverflow.com/questions/356705/how-to-send-a-head...
458 people upvoted that question, 697 upvoted the answer, hundreds of duplicates of it point to it.
In a long man page, well-documented options might as well not exist.
You don't need the whole manual all the time, and when someone is busy getting something done they shouldn't be hit with a "Hey, why don't you learn all of this"... they just want to get something done.
I'm willing to bet this is quicker than finding the question on stackoverflow:
And there's even an example.
Man pages = reference
tldr = recipes
People learn and use tools different ways. I'm a reference person, it sounds like you are too. But there exists a lot of people who find references hard, but example driven stuff easy (whereas I find examples limiting, and references endlessly useful).
Search for those people is difficult, as it's phrased by "this thing I want to do", and not "these keywords I already know".
tldr isn't for you and I... it's for those who prefer recipes over references.
I don't see anything wrong with tldr, I would have definitely loved to have something like that in the past. I do think that completely ignoring the man pages is a mistake though, since it requires just as little if not less effort as looking it up on stackoverflow, which in this case has the same answer anyways.
Rare manual page has an examples section, or sometimes manual is precise (or uses some terminology you do not know/remember), though is not user-friendly to instantly understand the impact of a command.
Like on github. You can find various cool tools, but some include a picture or a gif of example workflow at the top of README, and some don't. Especially I do not understand when some people show their web/gui tool and do not add a screenshot or a gif.
So it's the same with man pages for me: I want to use something I do not know or understand, I want to see explanation and/or example at the top explained in a simple manner. If I know the tool, usually I search for the option keywords instantly.
Just my $0.02.
(although they are still not at the top)
Only if you have the patience and time to go through the tons of flags to find the one you need -- and to decrypt the BS wordings used to describe what each flag does, especially if english isn't your first language.
>I don't know what niche this is supposed to fill?
The niche for straight to the point command invocation examples for the most common use cases.
That's nice, but for a quick "which command do I need?" scenario I prefer the examples that `tldr` can provide.
(1) Yes, some manpages do provide examples at the very bottom, but not all manpages do.
That's not the experience of many people. Or maybe, "taking the time to understand them" is not how they want to spend their time, and the mnemonics are bad because the use is not that frequent anyway.
Those same people spend more time joking about how complex the options are and linking that xkcd anyways.
It's an arbitrary set of command line flags and argument order.
So what's meant by "understanding" it, is basically "memorize".
Sure, if one devoted some time, they could memorize it. Like people can learn the PI to the nth digit.
But first, it's not just tar they use -- it's tens of other commands too.
Second, a lot of them have clashing flag order or slightly different names for the same arguments.
Third, most don't use them that frequently to make it worth it to sit and memorize it. Besides the infrequence of use means that simple memorizing once wont work, as they'll forget them without sitting down again later to refresh their memory. We can memorize complex vim commands because we use them everyday. Commands that we need once a month or once every 3 months, not so much.
It would be better for all if tar just did the obvious and intuitive thing.
And what is that obvious and intuitive thing?
Are you complaining about the need for a "-f" flag? If so, I'll agree, tar could take files the same way cat does. Tar's showing its age here, and would get a better interface without it.
But all the other flags are there for a reason, are the obvious mnemonic choices, and are the same ones used on other similar commands.
tar eXtract Ze File
tar Compress Ze File