TLDR pages
tldr-pages.github.io
tldr-pages.github.io
If you want a fast way to read the EXAMPLES section only for a command, here is a shell function which creates an ‘eg’ command which only displays the “EXAMPLES” section of manual pages:
eg(){
MAN_KEEP_FORMATTING=1 man "$@" 2>/dev/null \
| sed --quiet --expression='/^E\(\x08.\)X\(\x08.\)\?A\(\x08.\)\?M\(\x08.\)\?P\(\x08.\)\?L\(\x08.\)\?E/{:a;p;n;/^[^ ]/q;ba}' \
| ${MANPAGER:-${PAGER:-pager -s}}
}
$ eg tar
EXAMPLES
Create archive.tar from files foo and bar.
tar -cf archive.tar foo bar
List all files in archive.tar verbosely.
tar -tvf archive.tar
Extract all files from archive.tar.
tar -xf archive.tar
$
Lots of reasons they didn't add examples earlier. Maybe nobody happened to care, but if you submit a patch, they'll gladly accept it? Why so cynical?
Perhaps with a switch (man --tldr) or something?
Wouldn't a project to add those short examples to manpages be good?
See man(7), man-pages(7)
With a handful of commands i've got the tldr pages rendering in man:
mkdir /usr/local/share/man/man0/
pandoc -f markdown_github -t html https://raw.githubusercontent.com/tldr-pages/tldr/master/pages/common/tar.md > /usr/local/share/man/man0/tar.0.html
export MANPAGER="`which lynx` -stdin"
man 0 tar
We really shouldn't be rewriting tools and fragmenting community effort to fit a new feature that is already 90% implemented.
edit: one idea I do like is having content that is easy to contribute to, such as man pages, in separate repositories. Contributing to open source projects for content writers can often be intimidating - having a pure text separate man page repo that all the distro's use would be great.
Distributions can then create documentation meta-repositories that include relevant doc repo's as submodules.
If i'm a debian volunteer and I edit a typo in the man page for tar it gets pushed/pull-req up the to main tar repo from where it gets pulled out everywhere else
Not an entirely well formed idea, but the goal is to both lower the threshold for contributing documentation to project and second eliminate the duplicate effort in currently maintaining docs (which the OP project is only further complicating). Git can sit underneath what to contributors looks like nothing more than a wiki.
[1] https://help.github.com/articles/editing-files-in-your-repos...
https://en.m.wikipedia.org/wiki/Man_page#3
Maybe [ed:1e] for "general commands - examples"?
man page categories (1, 2, 3, etc.) are organized by type of command. See: http://www.schweikhardt.net/man_page_howto.html#q2
Reviewing the convention for man pages, it seems like adding an EXAMPLES section to existing man pages is the correct way to augment the documentation.
Definitely support your position that improving existing documentation is the way to go. Just wanted to share my research on how man pages are supposed to work.
I might do some work on this - import the examples from tldr and bro and get them into the man pages, and hopefully find a way so that man pages are easier to contribute to.
Still, a readable manpage alternative is always welcome!
Have you ever tried hunting down the canonical source repo for any of those ancient commands? It's nigh-impossible for many (most?). Seriously, give it a try for one of the small ones that haven't been touched in a few years.
Just look at the timeline of the last 4 releases of Tar:
Tar 1.28 - 27 Jul 2014
Tar 1.27.1 - 17 Nov 2013
Tar 1.27 - 20 Oct 2013
Tar 1.26 - 12 Mar 2011
function tldr { curl https://raw.githubusercontent.com/tldr-pages/tldr/master/pages/common/$1.md; } function tldr($what) {
("common", "linux") | foreach {
try {
(iwr raw.githubusercontent.com/tldr-pages/tldr/master/pages/$_/$what.md).Content
return
}
catch{}
}
} function tldr() { curl -s https://raw.githubusercontent.com/tldr-pages/tldr/master/pages/common/"$1.md" | mad -; }
Very interesting tools. I still don't know how to navigate man pages to find what I need.
Just `dtrx yourarchive.tar.xz`.
"In UNIX or short-option style, each option letter is prefixed with a single dash, as in other command line utilities. If an option takes argument, the argument follows it, either as a separate command line word, or immediately following the option. However, if the option takes an optional argument, the argument must follow the option letter without any intervening whitespace, as in -g/tmp/snar.db. Any number of options not taking arguments can be clustered together after a single dash, e.g. -vkp. Options that take arguments (whether mandatory or optional), can appear at the end of such a cluster, e.g. -vkpf a.tar."
When you have several alternative optional syntaxes for the commands, and you mix them with several different mandatory syntaxes for the parameters, the result is way more complex than merely "know five simple parameters for 99% use cases".
The following are all valid ways to do exactly the same thing:
tar cfv a.tar /etc
tar -cvf a.tar /etc
tar -c -v -f a.tar /etc
tar --create --file a.tar --verbose /etc
tar --cre --file=a.tar --verb /etc
This offers lots of flexibility, but also means that it will be hard to remember the exact syntax, and that examples that you come by on the net will all look wildly different, making it hard to learn the commands and create a habit by exposure to examples.
But generally, it is not a "tl;dr" that I am looking for in man pages, it is that one thing I need not very often, but can't remember, like "what switch does `git pull` take to rebase" (ok, not very good of an example, but since these are things I "can't remember", I can't pull one out of my head right now). And for these cases, `less`, my default pager, has excellent searching capabilities.
For instance, I needed to check how to tell OpenVPN CLI client to take username and password from a file instead of stdin. I knew I had done it before, but didn't know which flag it was... just the third instance of "username" on the openvpn manpage called it out (--auth-user-pass). Such things, are IMO, more often needed, but not something a tl;dr would cover.
Great project anyways :)
I don't know what niche this is supposed to fill?
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.
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)
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
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.
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.
+1 Comment of the day.
If you're already down to the command line, running UNIX commands, and using TLDR you are way beyond "buying fish at the supermarket".
And why should you "learning how to use those tools", when what you really want from those tools are the use cases TLDR already covers?
My eyeballs are strained from rolling every time I read some very sage person on SO or HN reply to a well-phrased question or comment with a terse "it's all in the docs".
As if 90% of use cases aren't covered by 5 examples. As if we all have unlimited time to spend on reading docs and manpages and "learning how to use the tools". As if there is some intrinsic virtue to "learning how to use the tools". As if the very purpose of sites like SO are something other than distilling the information in docs into some other, more readable form. As if there are no man pages or docs that are absolutely incomprehensible and worth ignoring.
No, sorry, this attitude is just another manifestation of standard tech machismo: "real men do it the hard way". Good luck with that!
But I agree completely. The entire point of computers is doto mechanize doing things, to essentially be "lazy", aka more efficient.
In the `tar` case if you know what c, x, v, z and f stand for you can cover 99% of the tar use cases because those can be combined. You learn 5 letters and have now access to 8 different commands (`{c,x}[v][z]f`). Learn one more letter, `t`, and you can combine it with your existing knowledge to have 3 more commands (tf, tvf, tzvf).
Tl;dr: Blame the software stack.
If you need more than the supermarket... then learn how to fish?
There's always a wrong way to use something. The good thing is that this is not being promoted as a replacement, but rather a helpful addition. I see it very useful as an alternative to hunting down for tutorials before you want to use some tool to figure out the details (a good example in this case would be something like lxc/lxd) or as a quick memory jogger, the examples that can be provided in a tldr man page could even have a specific context, like a cheatsheet kind of a man page.
At least personally, I need to do thing X and to achieve that I know I need to use tool Y. I read the man page of Y and very satisfyingly do the thing X. A month from now I have to do something similar to X and cannot for the life of me remember what freakish incantations need to be performed in order to do the same thing so I have to go through the man page again. This is where I'd like the tl/dr of it. I don't need Y often enough to actually warrant spending much time on learning to use the niche cli it requires..
Also perhaps have a tldr page on how to read man pages could be useful.
The important first step in learning how to use a command line tool is to have a first working example, i.e. you've made the tool do something you wanted. From there, all you need to know is how to find out more about what it can do. Skim read through some examples, anything else you think could be useful? Try it out. The rest can be forgotten. There's no harm in keeping knowledge outside our memory if we know how to research it if needed.
No, that’s not like saying that. `man tar` tells you which option to use for each use case; not the detailed algorithm of each compression algorithm.
And then there are the sad misguided souls using fish as their login shells (I kid, I kid…).
As many commenters have noted, it is possible to accomplish the goals of TLDR by improving existing man pages, without establishing a separate documentation system. A man page can be formatted to include any number of sections. All that is needed is an EXAMPLES section that lists examples for typical command usage.
Here are instructions for creating a man page: http://www.schweikhardt.net/man_page_howto.html#q3
Side note... isn't the usage of TL;DR in this project incorrect? TL;DR is a synonym for "abstract", "synopsis", and "executive summary". It is already confusing enough to use TL;DR in place of those words without overloading the term to mean "tasks", "example usage", or "typical use cases".
Adding EXAMPLE/SYNOPSIS to existing man pages helps a little, but tldr is squarely aimed at lowering the barrier for entry.
All of the materials you mentioned are for informing/entertaining people, not training them to acquire new skills. There is a field of study specifically for this: education.
Also, be less patronising.
I'm definitely not suggesting that writing useful documentation is easy. I agree with you that it takes work to write documentation and training material that people can use.
Not my intent for the prior post to be patronizing. Sorry it came across that way.
* How do I create a man page? (you answered this one)
* Where is the vcs repo for tar? (I think it's this one git.savannah.gnu.org/tar.git)
* I cloned the repo, but I don't see a contributing guide. Looks like I need to create an account and submit a patch online?
* Do I need to let the mailing list know about it? How do code reviews work?
None of these steps are dealbreakers, but together it all adds up to more unknowns I need to figure out before I can contribute. If existing projects make their contributing process smoother then I think we'll see more of this effort go directly to them.
I work at a company where the typical employee is 20-30 years older than I am. It is often a struggle to get people to adapt to change, the key is to persevere. As an example, I just finished participating in a 4-year effort to get my organization to adopt Git!
Often, projects like TLDR are necessary as proofs of concept to help the old guard understand the value of an idea or initiative. Even something as simple as this discussion existing might help people see an unmet need or expectation exists. And sometimes, when the old guard fails to respond, it is worth spinning those projects off with a group who sees the "new way" as clearly as breathing oxygen and replacing the old way of doing things completely.
Your list of bullets is a good one. To be honest with you, I've only contributed to open source docs a small number of times, submitting merge requests to Canonical. So, I will give updating a man page a try and see if I can figure it out.
function man {
cat <(tldr $1) <(/usr/bin/man $1) | less
}Even better: it'd be nice if there was a repository of just content that was structured in some standardized way. Then, some MVC-like system could easily consume all of the content.
Now, did I misunderstand or does this need npm?
example usage:
bro man
even allows user submission/voting on answers
bropages.org