6 ms·

Wow, a man page that is actually readable and understandable. I've been using Linux for years, and never once have I seriously looked at a man page. One of the

Wow, a man page that is actually readable and understandable. I've been using Linux for years, and never once have I seriously looked at a man page. One of the more useless pieces of advice Linux beginners are given is to `man [tool]`. The documentation often has tonnes of useless information and no examples. It's frustrating, and it's also why projects like tldr[0] have gotten so popular. But, the page linked in the OP is actually brilliant. It's easy to read, has examples, compartmentalises into sections that are relevant to different people. It's a step in the right direction. Note: I'm not saying there aren't other pages like OP. There probably are, but the vast majority are not. [0] https://github.com/tldr-pages/tldr https://github.com/tldr-pages/tldr

ekr 10y ago
One place where the MSDN docs is way ahead of the manpages is the documentation of function paramters. For instance, here's the ouput of man 2 write. ssize_t write(int fd, const void *buf, size_t count); DESCRIPTION write() writes up to count bytes from the buffer pointed buf to the file referred to by the file descriptor fd. The number of bytes written may be less than count if, for example, there is insufficient space on the underlying physical medium, or the RLIMIT_FSIZE resource limit is encountered (see setrlimit(2)), or call was interrupted by a signal handler after having written less than count bytes. (See also (7).) For a seekable file (i.e., one to which lseek(2) may be applied, for example, a regular file) writing takes place at the file offset, and the file offset is incremented by the number of bytes actually written. If the file was open(2)ed with O_APPEND, the file offset is first set to the end of the file before writing. The adjustment of the file offset and the write operation are performed as an atomic step. I have to go through a block of text scanning for the parameter I'm interested in. When I'm using the manpage as a reference (which is most of the time), this is less than ideal. MSDN indexes the documentation by parameter so you can quickly find what you're interested in. LE. Sample msdn link for comparison: https://msdn.microsoft.com/en-us/library/windows/desktop/aa365747(v=vs.85).aspx https://msdn.microsoft.com/en-us/library/windows/desktop/aa3... .
- qwertyuiop924 10y ago
  That's actually just one sentence you have to scan, so I don't totally see the issue.
  - viraptor 10y ago
    It could still be better. It could be 0 sentences to scan it it was formatted in a better way.
- brohee 10y ago
  That's under Linux (not sure if that man page is maintained by glibc or the kernel seeing as it is a syscall). That's pretty different under a system that cares : http://man.openbsd.org/OpenBSD-current/man2/write.2 http://man.openbsd.org/OpenBSD-current/man2/write.2
  - St-Clock 10y ago
    I'm sorry, how is it different than the linux example? They both describe all the parameters in the first sentence of the description.
    - brohee 10y ago
      I was mislead by the non formatting in the HN paste. Looking at https://linux.die.net/man/2/write https://linux.die.net/man/2/write it's about as good.
- koytch 10y ago
  Sections 2 and 3 contain the most readable man pages out there. The pages in sections 1 and 8 are often terrible, being the result of some texinfo->man filter.
- pjc50 10y ago
  One of the things that never ceases to amaze me is how slow MSDN is. It feels faster to look something up on stackoverflow, even if it's not as well organised. Version-specificness on MSDN is often a little odd. I do Windows CE and for some reason Google returns hits from the Wince5 docs more often than the rest, and it's not straightforward to get to the docs for a different version. Sometimes this is important.
qwertyuiop924 10y ago
man pages are quite useful as reference documents. Which is their intended purpose.
- tmsbrg 10y ago
  I have the idea of creating a tool which is more like a tutorial for commands rather than the reference that `man` is. Has anyone made something like that before? I thought of giving it a name like `tutor`. Where you can use it without arguments for a general shell tutorial and with arguments for a mini-tutorial about a command $ tutor Welcome to the Bash command shell. This is a short tutorial about how (and why) to use the shell... $ tutor ls Use `ls` to view files in the current directory or one you specify. Examples: - ls Lists current directory (excluding files starting with a ., these are "hidden files") - ls -A Lists current directory including hidden files ... === Something like that at least. I think one of the worst things about the shell is finding out about the functionality there actually is, so having something like that built in could be handy. Maybe you could also have it do something like `tutor copy file` and have it find and list commands that fit the description.
  - prashnts 10y ago
    How about tldr-pages? [1] [1] https://tldr-pages.github.io/ https://tldr-pages.github.io/
    - tmsbrg 10y ago
      That does look a lot better! Bit weird that the main client requires Node.JS though.
      - prashnts 10y ago
        Yeah, the node-js client isn't fast either. There's a client written in C and available from homebrew: `brew install tldr`.
andrewchambers 10y ago
Try a project like freebsd or openbsd for better man pages that are centrally curated.
jlgaddis 10y ago
> One of the more useless pieces of advice Linux beginners are given is to `man [tool]`. On the other hand, when I was first introduced to Linux ~20 years ago, I didn't have an "always-on" Internet connection and web sites weren't that popular. Probably 90% of what I learned in the first few years or so came from the man pages and a locally downloaded copy of the guides and howto's from TLDP [0]. I might also mention that not all man pages are created equal. I've seen some in Ubuntu that serve no purpose other than wasting bytes on the disk while some of those in OpenBSD act as a single source for everything one needs to know about <tool>. [0]: http://www.tldp.org/ http://www.tldp.org/
- jasoncchild 10y ago
  Same here; I was constrained to what was on my stack of floppies comprising my Slackware dist
  - jlgaddis 10y ago
    Slackware was the first Linux distro I ever installed on my own machine (I think that was the case for most of us at that time). I can remember very well trying to scrounge up enough floppies to write out the "A" and "N" sets -- the minimum needed to have a functional system with working "networking" (in my case, dial-up). After struggling for days to get a working "chat script", I finally managed to get online. I don't miss it but, in a way, it was sort of a "rite of passage" and you were forced to learn how your system really worked.
- Anthony-G 10y ago
  Similar situation for me. My first Linux distribution was Red Hat 5.2 which included an off-line copy of the Linux Documentation Project on the CD (as did other contemporary distros such as Mandrake). Since I only had a slow dial-up connection, I found these off-line copies to be an invaluable resource. I remember using Lynx to read Guides and Howtos during the two weeks it took me to get X working on my old laptop. After those early days, I hadn’t looked at the LDP site in ages but about 4/5 years ago I looked at the project again with a view towards contributing (now that I know more about GNU/Linux and Unix in general). However, it looks like the project was (is) largely moribund and I got the impression that the active community had dwindled significantly over the past 15 years or so – which is a pity.
hk__2 10y ago
I’ve been using Linux for years too, and I learned more useful things about Bash with `man bash` than anything I could find on the web.
- pjc50 10y ago
  For a while I had a printout of the bash manpage, neatly bound. It's something like 60 pages. Nroff actually produces great print output, which hardly anyone ever uses it for these days.
  - rkowalick 10y ago
    I don't think anything matches paper in terms of annotatability. I print things put all the time to just mark them up with red pen.
    - cx1000 10y ago
      I don't know, I saw a Microsoft surface commercial the other day... /s
thms0 10y ago
> One of the more useless pieces of advice Linux beginners are given is to `man [tool]`. You're such an idiot, my god. Maybe get yourself a brain and you'll understand all manpages :)
djhworld 10y ago
Thanks for that link to the TLDR project, looks kinda interesting. The fact that project exists though suggests to me there is a problem with the man page system in general.
pwdisswordfish 10y ago
Wow, a man page that is actually readable and understandable... just like any other man page. I've been using Linux for years, and never once have I seriously looked at replacements for man pages. In your average man page, I can look up even the most obscure option and know exactly how to use it and what it actually does. With a detailed enough man page, I don't even need to look anywhere else much of the time. It irritates me when I have to lookup documentation which isn't written in a similar format. (Say, LaTeX.) I don't see any appeal in "tldr pages" or "bro pages", and frankly, I get rather annoyed when every once in a while I see HN posts promoting projects like that which basically reinvent the square wheel instead of solving the real problems of man pages (which I'd say there are two: lack of hyperlinks and poor searchability).
- cx1000 10y ago
  I have never heard of bro pages before. It sounded like a pejorative but it's actually a thing http://bropages.org/ http://bropages.org/. I find them to be a lot of wasted time too and totally agree about the hyperlinks. As far as searching man pages, I do pretty well with the trusty forward slash. Would you prefer more semantic searching like google?
- catern 10y ago
  >solving the real problems of man pages (which I'd say there are two: lack of hyperlinks and poor searchability texinfo (info) has hyperlinks, and I can search through multiple manuals if that's what you mean by searchability. And it's probably already installed on your system.
  - pwdisswordfish 10y ago
    I can never remember which manual page contains a description of struct timespec, for example. Running apropos or man -k didn't help me. I only found out it's time.h(0p) by a lucky guess. Info is actually a quite decent idea, it's just executed poorly. Info pages are written like books, while I really miss the concise lexicon-like format of man pages. And it doesn't help that the default GNU info viewer is on one hand unusable for someone who isn't already an Emacs user, and on the other redundant for Emacs users. (I am the former. Fortunately, there's pinfo.)
whack 10y ago
I've generally found that most man pages are primarily useful for people who already know the basics of how to use that tool, and need to consult the man page in order to figure out how to understand/accomplish some specific functionality they're looking for. On the other hand, if you're completely new to the tool, man pages are pretty much useless like you mentioned. I generally just google for "<tool> tutorial" instead.
JdeBP 10y ago
It's worth noting that there's a difference between reference documentation and tutorials. The world needs both, of course. The user manual on Unices and Linux operating systems is meant to be reference doco. In the BSD world, in addition to the user manuals there are the various handbooks and guides: * https://freebsd.org/doc/handbook/ https://freebsd.org/doc/handbook/ * https://netbsd.org/docs/guide/en/ https://netbsd.org/docs/guide/en/ * https://www.trueos.org/handbook/trueos.html https://www.trueos.org/handbook/trueos.html * http://dragonflybsd.org/docs/handbook/ http://dragonflybsd.org/docs/handbook/ The Linux world has the Linux Documentation Project, but that is of variable quality, has patchy coverage, and is wildly outdated in some areas. There's a collaborative project on Wikibooks, as well. * https://en.wikibooks.org/wiki/Guide_to_Unix https://en.wikibooks.org/wiki/Guide_to_Unix
paulddraper 10y ago
For beginners, sure. Point them to tutorials or heavily abbreviated documentation. But I want to list all commits in the topological order they are in the graph, or need to understand date format specifiers, man git-log . I actually think quite highly of git's man pages for anything more than rudimentary first steps.

ekr 10y ago

One place where the MSDN docs is way ahead of the manpages is the documentation of function paramters. For instance, here's the ouput of man 2 write. ssize_t write(int fd, const void *buf, size_t count); DESCRIPTION write() writes up to count bytes from the buffer pointed buf to the file referred to by the file descriptor fd. The number of bytes written may be less than count if, for example, there is insufficient space on the underlying physical medium, or the RLIMIT_FSIZE resource limit is encountered (see setrlimit(2)), or call was interrupted by a signal handler after having written less than count bytes. (See also (7).) For a seekable file (i.e., one to which lseek(2) may be applied, for example, a regular file) writing takes place at the file offset, and the file offset is incremented by the number of bytes actually written. If the file was open(2)ed with O_APPEND, the file offset is first set to the end of the file before writing. The adjustment of the file offset and the write operation are performed as an atomic step. I have to go through a block of text scanning for the parameter I'm interested in. When I'm using the manpage as a reference (which is most of the time), this is less than ideal. MSDN indexes the documentation by parameter so you can quickly find what you're interested in. LE. Sample msdn link for comparison: https://msdn.microsoft.com/en-us/library/windows/desktop/aa365747(v=vs.85).aspx https://msdn.microsoft.com/en-us/library/windows/desktop/aa3... .

qwertyuiop924 10y ago
That's actually just one sentence you have to scan, so I don't totally see the issue.
- viraptor 10y ago
  It could still be better. It could be 0 sentences to scan it it was formatted in a better way.
brohee 10y ago
That's under Linux (not sure if that man page is maintained by glibc or the kernel seeing as it is a syscall). That's pretty different under a system that cares : http://man.openbsd.org/OpenBSD-current/man2/write.2 http://man.openbsd.org/OpenBSD-current/man2/write.2
- St-Clock 10y ago
  I'm sorry, how is it different than the linux example? They both describe all the parameters in the first sentence of the description.
  - brohee 10y ago
    I was mislead by the non formatting in the HN paste. Looking at https://linux.die.net/man/2/write https://linux.die.net/man/2/write it's about as good.
koytch 10y ago
Sections 2 and 3 contain the most readable man pages out there. The pages in sections 1 and 8 are often terrible, being the result of some texinfo->man filter.
pjc50 10y ago
One of the things that never ceases to amaze me is how slow MSDN is. It feels faster to look something up on stackoverflow, even if it's not as well organised. Version-specificness on MSDN is often a little odd. I do Windows CE and for some reason Google returns hits from the Wince5 docs more often than the rest, and it's not straightforward to get to the docs for a different version. Sometimes this is important.

qwertyuiop924 10y ago

man pages are quite useful as reference documents. Which is their intended purpose.

tmsbrg 10y ago
I have the idea of creating a tool which is more like a tutorial for commands rather than the reference that `man` is. Has anyone made something like that before? I thought of giving it a name like `tutor`. Where you can use it without arguments for a general shell tutorial and with arguments for a mini-tutorial about a command $ tutor Welcome to the Bash command shell. This is a short tutorial about how (and why) to use the shell... $ tutor ls Use `ls` to view files in the current directory or one you specify. Examples: - ls Lists current directory (excluding files starting with a ., these are "hidden files") - ls -A Lists current directory including hidden files ... === Something like that at least. I think one of the worst things about the shell is finding out about the functionality there actually is, so having something like that built in could be handy. Maybe you could also have it do something like `tutor copy file` and have it find and list commands that fit the description.
- prashnts 10y ago
  How about tldr-pages? [1] [1] https://tldr-pages.github.io/ https://tldr-pages.github.io/
  - tmsbrg 10y ago
    That does look a lot better! Bit weird that the main client requires Node.JS though.
    - prashnts 10y ago
      Yeah, the node-js client isn't fast either. There's a client written in C and available from homebrew: `brew install tldr`.

andrewchambers 10y ago

Try a project like freebsd or openbsd for better man pages that are centrally curated.

jlgaddis 10y ago

> One of the more useless pieces of advice Linux beginners are given is to `man [tool]`. On the other hand, when I was first introduced to Linux ~20 years ago, I didn't have an "always-on" Internet connection and web sites weren't that popular. Probably 90% of what I learned in the first few years or so came from the man pages and a locally downloaded copy of the guides and howto's from TLDP [0]. I might also mention that not all man pages are created equal. I've seen some in Ubuntu that serve no purpose other than wasting bytes on the disk while some of those in OpenBSD act as a single source for everything one needs to know about <tool>. [0]: http://www.tldp.org/ http://www.tldp.org/

jasoncchild 10y ago
Same here; I was constrained to what was on my stack of floppies comprising my Slackware dist
- jlgaddis 10y ago
  Slackware was the first Linux distro I ever installed on my own machine (I think that was the case for most of us at that time). I can remember very well trying to scrounge up enough floppies to write out the "A" and "N" sets -- the minimum needed to have a functional system with working "networking" (in my case, dial-up). After struggling for days to get a working "chat script", I finally managed to get online. I don't miss it but, in a way, it was sort of a "rite of passage" and you were forced to learn how your system really worked.
Anthony-G 10y ago
Similar situation for me. My first Linux distribution was Red Hat 5.2 which included an off-line copy of the Linux Documentation Project on the CD (as did other contemporary distros such as Mandrake). Since I only had a slow dial-up connection, I found these off-line copies to be an invaluable resource. I remember using Lynx to read Guides and Howtos during the two weeks it took me to get X working on my old laptop. After those early days, I hadn’t looked at the LDP site in ages but about 4/5 years ago I looked at the project again with a view towards contributing (now that I know more about GNU/Linux and Unix in general). However, it looks like the project was (is) largely moribund and I got the impression that the active community had dwindled significantly over the past 15 years or so – which is a pity.

hk__2 10y ago

I’ve been using Linux for years too, and I learned more useful things about Bash with `man bash` than anything I could find on the web.

pjc50 10y ago
For a while I had a printout of the bash manpage, neatly bound. It's something like 60 pages. Nroff actually produces great print output, which hardly anyone ever uses it for these days.
- rkowalick 10y ago
  I don't think anything matches paper in terms of annotatability. I print things put all the time to just mark them up with red pen.
  - cx1000 10y ago
    I don't know, I saw a Microsoft surface commercial the other day... /s

thms0 10y ago

> One of the more useless pieces of advice Linux beginners are given is to `man [tool]`. You're such an idiot, my god. Maybe get yourself a brain and you'll understand all manpages :)

djhworld 10y ago

Thanks for that link to the TLDR project, looks kinda interesting. The fact that project exists though suggests to me there is a problem with the man page system in general.

pwdisswordfish 10y ago

Wow, a man page that is actually readable and understandable... just like any other man page. I've been using Linux for years, and never once have I seriously looked at replacements for man pages. In your average man page, I can look up even the most obscure option and know exactly how to use it and what it actually does. With a detailed enough man page, I don't even need to look anywhere else much of the time. It irritates me when I have to lookup documentation which isn't written in a similar format. (Say, LaTeX.) I don't see any appeal in "tldr pages" or "bro pages", and frankly, I get rather annoyed when every once in a while I see HN posts promoting projects like that which basically reinvent the square wheel instead of solving the real problems of man pages (which I'd say there are two: lack of hyperlinks and poor searchability).

cx1000 10y ago
I have never heard of bro pages before. It sounded like a pejorative but it's actually a thing http://bropages.org/ http://bropages.org/. I find them to be a lot of wasted time too and totally agree about the hyperlinks. As far as searching man pages, I do pretty well with the trusty forward slash. Would you prefer more semantic searching like google?
catern 10y ago
>solving the real problems of man pages (which I'd say there are two: lack of hyperlinks and poor searchability texinfo (info) has hyperlinks, and I can search through multiple manuals if that's what you mean by searchability. And it's probably already installed on your system.
- pwdisswordfish 10y ago
  I can never remember which manual page contains a description of struct timespec, for example. Running apropos or man -k didn't help me. I only found out it's time.h(0p) by a lucky guess. Info is actually a quite decent idea, it's just executed poorly. Info pages are written like books, while I really miss the concise lexicon-like format of man pages. And it doesn't help that the default GNU info viewer is on one hand unusable for someone who isn't already an Emacs user, and on the other redundant for Emacs users. (I am the former. Fortunately, there's pinfo.)

whack 10y ago

I've generally found that most man pages are primarily useful for people who already know the basics of how to use that tool, and need to consult the man page in order to figure out how to understand/accomplish some specific functionality they're looking for. On the other hand, if you're completely new to the tool, man pages are pretty much useless like you mentioned. I generally just google for "<tool> tutorial" instead.

JdeBP 10y ago

It's worth noting that there's a difference between reference documentation and tutorials. The world needs both, of course. The user manual on Unices and Linux operating systems is meant to be reference doco. In the BSD world, in addition to the user manuals there are the various handbooks and guides: * https://freebsd.org/doc/handbook/ https://freebsd.org/doc/handbook/ * https://netbsd.org/docs/guide/en/ https://netbsd.org/docs/guide/en/ * https://www.trueos.org/handbook/trueos.html https://www.trueos.org/handbook/trueos.html * http://dragonflybsd.org/docs/handbook/ http://dragonflybsd.org/docs/handbook/ The Linux world has the Linux Documentation Project, but that is of variable quality, has patchy coverage, and is wildly outdated in some areas. There's a collaborative project on Wikibooks, as well. * https://en.wikibooks.org/wiki/Guide_to_Unix https://en.wikibooks.org/wiki/Guide_to_Unix

paulddraper 10y ago

For beginners, sure. Point them to tutorials or heavily abbreviated documentation. But I want to list all commits in the topological order they are in the graph, or need to understand date format specifiers, man git-log . I actually think quite highly of git's man pages for anything more than rudimentary first steps.