3 ms·

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

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?

Mojah 11y ago
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.
- mystikal 11y ago
  The difference between man gcc and tldr gcc is dramatic.
- Gravityloss 11y ago
  Even the examples are usually completely alien to real usage.
nailer 11y ago
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)
trymas 11y ago
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.
- justincormack 11y ago
  You mean like the excellent FreeBSD man pages, eg tar here https://www.freebsd.org/cgi/man.cgi?query=tar&apropos=0&sektion=0&manpath=FreeBSD+10.2-RELEASE&arch=default&format=html https://www.freebsd.org/cgi/man.cgi?query=tar&apropos=0&sekt... (although they are still not at the top)
jehna1 11y ago
This. https://xkcd.com/1168/ https://xkcd.com/1168/
- chrismorgan 11y ago
  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.)
- hk__2 11y ago
  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.
  - coldtea 11y ago
    >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.
    - tazjin 11y ago
      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.
      - coldtea 11y ago
        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.
buro9 11y ago
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 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-header-using-a-http-request-through-a-curl-call 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.
- Tiksi 11y ago
  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 http://paste.click/HrdrGW And there's even an example.
  - buro9 11y ago
    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.
    - Tiksi 11y ago
      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.
coldtea 11y ago
>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.

Mojah 11y ago

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.

mystikal 11y ago
The difference between man gcc and tldr gcc is dramatic.
Gravityloss 11y ago
Even the examples are usually completely alien to real usage.

nailer 11y ago

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)

trymas 11y ago

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.

justincormack 11y ago
You mean like the excellent FreeBSD man pages, eg tar here https://www.freebsd.org/cgi/man.cgi?query=tar&apropos=0&sektion=0&manpath=FreeBSD+10.2-RELEASE&arch=default&format=html https://www.freebsd.org/cgi/man.cgi?query=tar&apropos=0&sekt... (although they are still not at the top)

jehna1 11y ago

This. https://xkcd.com/1168/ https://xkcd.com/1168/

chrismorgan 11y ago
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.)
hk__2 11y ago
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.
- coldtea 11y ago
  >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.
  - tazjin 11y ago
    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.
    - coldtea 11y ago
      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.

buro9 11y ago

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 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-header-using-a-http-request-through-a-curl-call 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.

Tiksi 11y ago
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 http://paste.click/HrdrGW And there's even an example.
- buro9 11y ago
  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.
  - Tiksi 11y ago
    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.

coldtea 11y ago

>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.