TLDR pages(tldr-pages.github.io)
tldr-pages.github.io
TLDR pages
http://tldr-pages.github.io/
116 comments
I don't mean to sound cynical, but if oft-used man pages haven't already added "EXAMPLES" sections over the last 30 years, how likely is it that they'd add them now? This project exists because man has failed to as useful as it needs to be for current users. I don't think that adding this info to the "EXAMPLES" sections will help anything, personally.
> if oft-used man pages haven't already added "EXAMPLES" sections over the last 30 years, how likely is it that they'd add them now?
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?
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?
[deleted]
[deleted]
I do find TLDR useful, but is there anything preventing adding it as a standard section of the actual manpages we all use?
Perhaps with a switch (man --tldr) or something?
Wouldn't a project to add those short examples to manpages be good?
Perhaps with a switch (man --tldr) or something?
Wouldn't a project to add those short examples to manpages be good?
You can add a section 0 to man pages for example (tldr) versions. Man also already supports rendering HTML if that is the preferred format that contributors want to write.
With a handful of commands i've got the tldr pages rendering in man:
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.
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.
Generally agree that augmenting existing man pages is then way to go. However, using a new number to categorize "use cases" or "examples" is probably incorrect.
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.
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.
Thanks, I remembered it being extensible. Turns out that section is a char in the man code so it could easily be a new section or a switch to extract the examples.
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.
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.
I like the idea of adding a section for examples, but not sure "0" would be the best place for it - as it's already taken by C headers:
https://en.m.wikipedia.org/wiki/Man_page#3
Maybe [ed:1e] for "general commands - examples"?
https://en.m.wikipedia.org/wiki/Man_page#3
Maybe [ed:1e] for "general commands - examples"?
why not 1e? 3 is library functions
(I am interested in your edit.) Are you suggesting a separate documentation repository for each project or a single repository shared by some specific centralized entity that somehow maintains man pages for everyone?
Both. First each project would have a documentation repository. This exists with gh-pages but it is a separate branch, which is confusing to newbies. Having a repo with just content would make it easier to open to contributors who are non-developers (and take advantage of features like inline editing in GitHub[1] (although that needs to automate the fork step as well))
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...
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...
For each example in the TLDR pages repository, find the corresponding man page
on your system, render the markdown to groff, insert it as EXAMPLE section
before AUTHOR/SEE ALSO or at the end of the file if these sections are missing.
See man(7), man-pages(7)
See man(7), man-pages(7)
Manpages already have a one-line summary, check out the "whatis" and "apropos" commands. You could combine that with the frequently occuring "EXAMPLES" section to build a similar tool.
Maybe instead of creating something entirely new we could improve the existing thing, that is prepend man pages with some examples?
There have been discussions in the past about "standardizing" on an Examples section. It is usually what I miss the most in any manual.
The man maintainers, at least from my own dealings with them, often don't like contributors. "Examples are nice, and I like your changes, but what if Paul Vixie doesn't?" It's easier to fork man completely and take it away from them, Xorg style.
"I've done this, to fix the problem."
"Ah yeah, no need; that problem's been discussed in the past".
"Ok, what happened"
"IT...WAS...DISCUSSED!"
You're free to try to incorporate these into the man pages. The creators of this (brilliant idea, btw, just what I have desired so many times in the past) are under no obligation to do so.
I find it rather redundant to bropages: http://bropages.org/
Still, a readable manpage alternative is always welcome!
Still, a readable manpage alternative is always welcome!
To everyone suggesting people send patches in to the original repos instead of using this, or anything like it:
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.
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.
If if you do good luck getting your patch merged, wait a year for the next release, and then sit back and wait a few years (if ever) for the versions to trickle into real distributions
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
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
Instead of installing one of the clients, it might be easier to just put this line into your bash.rc:
function tldr { curl https://raw.githubusercontent.com/tldr-pages/tldr/master/pages/common/$1.md; }Even better if you pipe it to a markdown renderer:
function tldr() { curl -s https://raw.githubusercontent.com/tldr-pages/tldr/master/pages/common/"$1.md" | mad -; }
there's also linux/osx/.. pages; but I like the idea so here's some Powershell
function tldr($what) {
("common", "linux") | foreach {
try {
(iwr raw.githubusercontent.com/tldr-pages/tldr/master/pages/$_/$what.md).Content
return
}
catch{}
}
}Internet access is not a given at all times. One is often more likely to need manuals when there is a problem with it.
Well to be fair, you can just use the man pages if you don't have network access. Or you could git clone the repo and print it from the repo. I think his point is that this is a problem that is easy to overengineer and really doesn't need that much work to be done.
Also see bropages! http://bropages.org/
Very interesting tools. I still don't know how to navigate man pages to find what I need.
Very interesting tools. I still don't know how to navigate man pages to find what I need.
Yep, also have used them for a while and even though they're lacking content still, the concept I'd say is rather better than tldr-pages. Contributing is easier and documentation is specifically focused on examples, not trying to replace the original documentation, which should be improved separately, if needed.
One thing I love about Perl, which has seemed sorely lacking in many other languages, is the habit of documenting all modules with a "Synopsis" section, which is essentially short examples of use. A good 50% of modules I use I don't need to read further!
As a side note, `dtrx` is a sane alternative to `tar` that do the right thing by default. http://brettcsmith.org/2007/dtrx/
Just `dtrx yourarchive.tar.xz`.
Just `dtrx yourarchive.tar.xz`.
I honestly don't understand the meme of "tar is so hard to use". You only need to know like five parameters (xcvfz) for 99% of use cases, and they're pretty easy to understand.
From the manual:
"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.
"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.
Looks great, theres also a Brew formula. Not sure I'll remember "dtrx" though...
It might help if you remember it as "Do The Right eXtraction" (and hopefully tab-complete after dtr, to deal with the final x).
I think man pages aren't always verbose or unreadable. In fact, most of the time, they are pretty easy on eyes for me.
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 :)
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 :)
reminds me of http://bropages.org/
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?
Man pages are manuals.
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.
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.
[deleted]
I mean I don't disagree with the idea behind what you said, but we do have search. You don't have to read the man pages like a book to get use out of them.
I'm willing to bet this is quicker than finding the question on stackoverflow:
http://paste.click/HrdrGW
And there's even an example.
I'm willing to bet this is quicker than finding the question on stackoverflow:
http://paste.click/HrdrGW
And there's even an example.
I'm not sure you understood.
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.
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.
Like I said, I don't disagree, and I can see the use people get from recipes. And yes, you're right that I'm a "if I need to google it more than 3 times, I'm reading the man pages" kind of person. However that stackoverflow answer is literally a copy and paste from the man pages, with an example (which the man pages I have also contains apparently). The information is the same, the method to search for it is different, but I'm willing to bet my way is faster ;)
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.
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.
Personally, sometimes I want just to see few basic examples at the front of the manual page, with inputs and outputs.
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.
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.
You mean like the excellent FreeBSD man pages, eg tar here https://www.freebsd.org/cgi/man.cgi?query=tar&apropos=0&sekt...
(although they are still not at the top)
(although they are still not at the top)
>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.
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.
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.
I like it because it introduces practical, real-world example commands. Most manpages don't offer those but instead list all parameters and potential input (1)
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 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.
Even the examples are usually completely alien to real usage.
The difference between man gcc and tldr gcc is dramatic.
Tar options are actually very easy once you take the time to understand them. Want to create an archive? use `-c`. Want to extract? It’s `-x`. From that you know you can use `tar -cf foo.tar foo` (`-f` lets you pass the archive name) and `tar -xf foo.tar`. Want to be verbose? Add `-v`. Want to use gzip compression? Add `-z`. There are a bunch of other options to do more, but just with that you can already understand 99% of what tar is used for.
>Tar options are actually very easy once you take the time to understand them.
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.
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.
But the time we're talking about to understand this is less than 5 minutes.
Those same people spend more time joking about how complex the options are and linking that xkcd anyways.
Those same people spend more time joking about how complex the options are and linking that xkcd anyways.
Let me rephrase. There's nothing much to "understand". This is not a logical puzzle or a physics lecture.
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.
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.
> 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.
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.
I saw something in a comment a few months ago that made it so i'll never forget this again.
tar eXtract Ze File
tar Compress Ze File
tar eXtract Ze File
tar Compress Ze File
I never got this. I memorised basic usage of tar very quickly and have never had any issues with it since; and even if you didn’t know how to use `tar`, surely `tar --help` would be worth a go? (It’d be the first thing I’d use for an unknown program.)
For some reason, I can't remember for my life how to use cpio, which I find worse than tar even though it has less options. I always mix up input/output mode, and I never remember how passthru mode works exactly.
TLDR pages are tasked based. Man pages are references to all possible switches in an app. Eg, the tar man page has a focus on tape archiving, referencing $TAPE and /dev/mt0 and didn't used to have examples (IIRC I added them to RHEL a decade ago but I'm not sure if they're still there)
The issue I have with this kind of projects is that people quickly accept that reading manpages is boring and that they should only use `tldr gcc` or a quick stackoverflow lookup instead of actually learning how to use their tools. It’s like learning how to fish vs. bying fish at the supermarket. Sure, if you know how to fish you can still buy at the supermarket if you’re lazy. But if you don’t you’re stuck with what’s at the supermarket.
>It’s like learning how to fish vs. bying fish at the supermarket. Sure, if you know how to fish you can still buy at the supermarket if you’re lazy. But if you don’t you’re stuck with what’s at the supermarket
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?
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?
Agreed 100 times over.
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!
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!
I’m not saying you shouldn’t use TLDR or StackOverflow. I’m just saying you could benefit from reading the manpage once instead of TLDR 10 times a day. That doesn’t mean you won’t forget most of the stuff and will use TLDR/SO to find it again but at least you’ll be more comfortable using the tool.
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).
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).
Great. Then put those options near the top. Why are options on man pages organized alphabetically? What common use case drives that decision?
Well, in a dictionary words are not listed at the beginning. The alphabet itself doesn’t have the most common letters at the beginning. What we should do is put the manpage examples at the beginning instead of the end.
The purpose of documentation is to describe the software. It's not machismo, it's the complexity inherent in the system. The man page for tar isn't poorly written, tar has just accrued many options. Of course there may be unhelpful answers to requests for help. It may also be that industrial technology (Unix) is not as simple or easy to use as consumer technology.
Tl;dr: Blame the software stack.
Tl;dr: Blame the software stack.
Shit, I meant to upvote you, but I flubbed my phone and hit the down arrow instead. HN must think this is a feature, considering how long it has been a probelm.
But I agree completely. The entire point of computers is doto mechanize doing things, to essentially be "lazy", aka more efficient.
But I agree completely. The entire point of computers is doto mechanize doing things, to essentially be "lazy", aka more efficient.
Continuing your tool analogy, if I used a hammer only to drive a nail, why would I need to read the whole manual of building a wooden house? Knowing your tool is important, but I find myself spending way too much time reading manpages and looking for how to accomplish a trivial task on Linux, so TLDR for most common (simple) use cases looks like a great idea.
Reading the manual once will save you a lot of time reading TLDR over and over. Which is not to say you won’t read it; but you’ll read it less than without reading the manual first.
I find this hard to believe. You probably need to read the man page and perform the action over and over again.
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..
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..
I doubt that. I don't try to memorize commands (even more so - manuals), so it's more like I'm reading manual over and over again, which takes more time than reading TLDR. I agree that it's important to understand what command is used for and what capabilities it has, but trying to remember all these flags by heart is waste of limited brain resources imho.
Nobody can be an expert in every single tool they use, furthermore it's a waste of time if you have the option of learning things when the need arises. Not only would you have forgotten most of the text of man pages after reading it, you're also unlikely to ever use most of the options you found in them.
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.
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.
How is this much different from today? plenty of people just learn what they need from Google for their use case without reading through man pages and understanding every option.
If you need more than the supermarket... then learn how to fish?
If you need more than the supermarket... then learn how to fish?
That's true, but I don't think it'd be a problem since you won't be able to really understand how something works and eventually you'd not know how to use the thing.
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.
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.
Thats like saying you dont know how to fish unless you learn the detailed operation of 10 different types of fishing boats. None of which you have access to, you're fishing from the dock and your budget is $20.
> Thats like saying you dont know how to fish unless you learn the detailed operation of 10 different types of fishing boats.
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.
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.
[deleted]
Yes but overall, isn't it better to at least have the choice to go to the supermarket? (As you kind of acknowledge in your own example.)
Yes I’m not saying you should never use tldr or similar tools; just that you could benefit from reading the manpages from time to time. I learnt more things from reading `man bash` than from any StackOverflow question or post on the Web.
Agreed, currently the pages only show quick syntax examples, would be good to have a brief description of the tool and what it does.
Also perhaps have a tldr page on how to read man pages could be useful.
Or this: http://www.tfug.org/helpdesk/general/man.html
Also perhaps have a tldr page on how to read man pages could be useful.
Or this: http://www.tfug.org/helpdesk/general/man.html
> It’s like learning how to fish vs. bying fish at the supermarket.
And then there are the sad misguided souls using fish as their login shells (I kid, I kid…).
And then there are the sad misguided souls using fish as their login shells (I kid, I kid…).
I was surprised the other day when I was reading something about containers, and the author explained what the touch command does.
"It’s like learning how to fish vs. bying fish at the supermarket. Sure, if you know how to fish you can still buy at the supermarket if you’re lazy. But if you don’t you’re stuck with what’s at the supermarket."
+1 Comment of the day.
+1 Comment of the day.
What if we put community energy into contributing improvements to existing man pages for open source projects?
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".
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".
Projects like this happen because it's easier to contribute here than to the existing manpages. As someone who came of age in a Github world, there's (perceived) friction preventing me from trying to contribute to a lot of tools from the old guard. Let's say I want to add some examples to the tar man page:
* 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.
* 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.
The friction you feel likely is more than just perceived. Perseverance can often break past it and sometimes a disruptive spinoff proves to be required.
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.
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.
agreed 100% when all you want to do is make a small tweak to some text spend literally hours trying to figure all that out just isn't worth it. Better to say "fuck it" and move on.
Historical man pages have been the comprehensive reference for a command. You can't write a document that serves both as a gentle introduction to a tool for a new user, and retain the encyclopedic list of every possible option.
Adding EXAMPLE/SYNOPSIS to existing man pages helps a little, but tldr is squarely aimed at lowering the barrier for entry.
Adding EXAMPLE/SYNOPSIS to existing man pages helps a little, but tldr is squarely aimed at lowering the barrier for entry.
For hundreds of years we've been writing summative introductions called "abstracts" to long documents called "journal articles", "lede" paragraphs introduce "journalism", and "introductions" summarize "books". People understand how to use these conventions. How is it easier for the end user to have to learn to install, use, and understand an additional tool chain? How is it easier for a project maintainer to manage documentation in multiple locations?
https://xkcd.com/1319/
https://xkcd.com/1319/
It's not easy? It's hard to write documentation that's suited for reference AND expert users AND new users.
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.
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 guess that for me the git man page does it's job as the quick summary for how that program works and git-scm.com/book is the training tool I rely on as a new user. There is so much to learn that a man page cannot concisely cover, like how to structure a collaborative workflow in a distributed team. For that, turning to a well written book has been key.
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.
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 does this deal with different versions of a utility having different flags/commands?
By only supporting the Mac OS X version, apparently, because neither my Debian, Fedora nor Arch have this `brew` tool mentioned on the home page.
Cool idea - but like others allude, it would be useful if the TRDR content was organized along with the man page content.
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.
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.
What about https://github.com/chrisallenlane/cheat ?
Didn't know about that one, thanks for the link! I've added it to the discussion at https://github.com/tldr-pages/tldr/issues/266
Yes! Thank you, all I want is an example of how to use the command. Man pages never help me, they give a bunch of non-concrete examples. I always just Google for the command and someone's blog post helps me out.
love the simplicity put in this little tool.
Incredibly easy to remember, gives the answer you need 95% of the times, makes it very easy to contribute with new stuff.
TL;DR a collection of TL;DRs for common *nix commands with clients to display the shorter docs
most useful thing ever. All you need in 90% of the time. Hope to see it in Redhat soon :)
Seems like most tools basically provide this with a -h or --help switch.
Brilliant idea!
Now, did I misunderstand or does this need npm?
Now, did I misunderstand or does this need npm?
As far as I see there are different clients available as options. You don't necessarily need npm but I don't know in what shape the clients are.
For example the go client seems broken to me (hard coded wrong tldr-page url, no caching, platform is always set to common) https://github.com/pranavraja/tldr
I like the idea. Maybe I will create a better Go client.
You can use the python one. I tried it and the npm one and the npm one seems like it's in much better shape (colors were all screwed up on the python one). so, I guess YMMV
there's also a ruby gem called bropages!(gem install bropages)
example usage:
bro man
even allows user submission/voting on answers
example usage:
bro man
even allows user submission/voting on answers
looks just like bro pages
bropages.org
bropages.org
Seems like a good idea, man pages can be almost comically obtuse at times.
I feel like the examples tldr entries should be required to be written by a third party other than the creator of the software. In my experience the creator of a piece of software or machine always thinks it is simple and writes the man page accordingly.
If there was anything the frozen computer interface of the 70s needed to complete itself, it was silly Internet neologisms. Thanks, author, for bringing the worst of several eras together.
[deleted]
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:
Usage:
(Previously: https://news.ycombinator.com/item?id=10025216, https://news.ycombinator.com/item?id=7123328)