4 ms·

> Note that the "rule of silence" (combined with the habit of writing documentation like longform essays) is also one factor that makes unix-like systems newbi

by dom0 10y ago

> Note that the "rule of silence" (combined with the habit of writing documentation like longform essays) is also one factor that makes unix-like systems newbie-unfriendly. (Famous example: trying to exit vi) $ man foo *scroll to the end with the EXAMPLES section* There should be an option for that. man --take-me-to-the-examples foo

vog 10y ago
(NOTE: The parent comment was edited. This response applies to the original parent comment that contained just the command line ("man foo" + EXAMPLE section) and nothing else.) Wow, I haven't seen such a blunt and unhelpful RFTM comment for a while. This comment is inappropriate in so many ways: 1) The unix systems have an inconsistent documentation mix of man pages, info pages, "-h", "-help", "--help", HTML docs, separate manuals (e.g. Debian Administrator's Handbook) and so on. 2) "man foo" leads to: "No manual entry for foo" 3) "man vi", as well as "man vim" both lead to a manpage that has no EXAMPLES section at all (see https://www.freebsd.org/cgi/man.cgi?query=vi https://www.freebsd.org/cgi/man.cgi?query=vi, https://www.freebsd.org/cgi/man.cgi?query=vim https://www.freebsd.org/cgi/man.cgi?query=vim) 4) The Vi(m) manpages explain only the command line arguments, not the editor commands. The latter are available by typing ":help" in the editor.
- swiley 10y ago
  You don't really need an "examples" section for vim, 90% of the time you just type "vim file" which the usage info probably covers well enough. You only need an "examples" section for something like zip.
  - vog 10y ago
    > you just type "vim file" which the usage info probably covers well enough This is wrong. If you just type "vim file", you don't get any usage info, not even in the status line. See also: https://news.ycombinator.com/item?id=13165795 https://news.ycombinator.com/item?id=13165795
setrofim_ 10y ago
You might find this intersting: https://github.com/tldr-pages/tldr https://github.com/tldr-pages/tldr
- BrockSamson 10y ago
  Thanks for this, you've just made my day!
- teddyh 10y ago
  That project is a symptom of manual pages not having good “EXAMPLES” sections. The examples on that web page should be contributed upstream to the manuals pages of the software that they are for.
  - setrofim_ 10y ago
    The issue isn't just the lack of EXAMPLES, but also with how man pages tend to be structured. They tend to be very "encyclopedic". There is a set ordering for sections, with a lot of them very verbose, and examples, when present, near the end. Options are often listed in alphabetic order, which doesn't usually correspond to how often they are used or useful. Man pages are OK when you're first learning how to use something; but if you're already familiar with a command and just need to remind yourself of a the specific sequence of options to achieve a desired result, they're not the most convenient. I think it's useful to have a tool that fulfills the latter purpose without worrying about the former.
    - JdeBP 10y ago
      Microsoft documentation was mentioned earlier in this discussion. One of the things that MSDN and TechNet doco does is have both "X reference" and "using X" sections. Manual pages are reference doco, in this way of organizing things. The FreeBSD, TrueOS, and related worlds put the "using" doco into what are often called "handbooks" or "guides". * NetBSD Guide: https://netbsd.org/docs/guide/en/ https://netbsd.org/docs/guide/en/ * FreeBSD Handbook: https://freebsd.org/doc/handbook/book.html https://freebsd.org/doc/handbook/book.html * DragonFlyBSD Handbook: https://www.dragonflybsd.org/docs/handbook/ https://www.dragonflybsd.org/docs/handbook/ * TrueOS User Guide: https://www.trueos.org/handbook/trueos.html https://www.trueos.org/handbook/trueos.html * PC-BSD User Guide: http://web.pcbsd.org/doc-archive/10.1.2/html/pcbsd.html http://web.pcbsd.org/doc-archive/10.1.2/html/pcbsd.html (viewable off-line directly in both PDF and HTML forms in /usr/local/share/pcbsd/doc/) Some parts of the Linux world do the same. upstart had the Upstart Cookbook for example: * http://upstart.ubuntu.com/cookbook/ http://upstart.ubuntu.com/cookbook/ The Linux Documentation Project was supposed to contain a wealth of this stuff, but large parts of it are seemingly moribund, and incomplete after decades or woefully outdated. Wikibooks tried to take up the slack with an "anyone can edit" Guide to Unix and a Linux Guide: * https://en.wikibooks.org/wiki/Guide_to_Unix https://en.wikibooks.org/wiki/Guide_to_Unix * https://en.wikibooks.org/wiki/Linux_Guide https://en.wikibooks.org/wiki/Linux_Guide If you want examples and doco that works from the basis of what you usually want to do, then these handbooks and guides are the places to go, not reference manuals.
teddyh 10y ago
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}} } Usage: $ 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 $
- eriknstr 10y ago
  Here's mine: examples () { man $1 | less +/^EXAMPLES } Usage: $ examples su EXAMPLES su -m man -c catman Starts a shell as user man, and runs the command catman. You will be asked for man's password unless your real UID is 0. Note that the -m option is required since user “man” does not have a valid shell by default. In this example, -c is passed to the shell of the user “man”, and is not interpreted as an argument to su. su -m man -c 'catman /usr/share/man /usr/local/man' Same as above, but the target command consists of more than a single word and hence is quoted for use with the -c option being passed to the shell. (Most shells expect the argument to -c to be a single word). su -m -c staff man -c 'catman /usr/share/man /usr/local/man' Same as above, but the target command is run with the resource limits of the login class “staff”. Note: in this example, the first -c option applies to su while the second is an argument to the shell being invoked. su -l foo Simulate a login for user foo. su - foo Same as above. su - Simulate a login for root.
  - teddyh 10y ago
    You probably still want the MAN_KEEP_FORMATTING=1 part, to keep colorization and bolding etc. in the manual page. Also, your solution does not respect the user’s pager preference; the user might prefer to read man pages in “w3m”, for instance.

by dom0 10y ago

vog 10y ago

(NOTE: The parent comment was edited. This response applies to the original parent comment that contained just the command line ("man foo" + EXAMPLE section) and nothing else.) Wow, I haven't seen such a blunt and unhelpful RFTM comment for a while. This comment is inappropriate in so many ways: 1) The unix systems have an inconsistent documentation mix of man pages, info pages, "-h", "-help", "--help", HTML docs, separate manuals (e.g. Debian Administrator's Handbook) and so on. 2) "man foo" leads to: "No manual entry for foo" 3) "man vi", as well as "man vim" both lead to a manpage that has no EXAMPLES section at all (see https://www.freebsd.org/cgi/man.cgi?query=vi https://www.freebsd.org/cgi/man.cgi?query=vi, https://www.freebsd.org/cgi/man.cgi?query=vim https://www.freebsd.org/cgi/man.cgi?query=vim) 4) The Vi(m) manpages explain only the command line arguments, not the editor commands. The latter are available by typing ":help" in the editor.

swiley 10y ago
You don't really need an "examples" section for vim, 90% of the time you just type "vim file" which the usage info probably covers well enough. You only need an "examples" section for something like zip.
- vog 10y ago
  > you just type "vim file" which the usage info probably covers well enough This is wrong. If you just type "vim file", you don't get any usage info, not even in the status line. See also: https://news.ycombinator.com/item?id=13165795 https://news.ycombinator.com/item?id=13165795

setrofim_ 10y ago

You might find this intersting: https://github.com/tldr-pages/tldr https://github.com/tldr-pages/tldr

BrockSamson 10y ago
Thanks for this, you've just made my day!
teddyh 10y ago
That project is a symptom of manual pages not having good “EXAMPLES” sections. The examples on that web page should be contributed upstream to the manuals pages of the software that they are for.
- setrofim_ 10y ago
  The issue isn't just the lack of EXAMPLES, but also with how man pages tend to be structured. They tend to be very "encyclopedic". There is a set ordering for sections, with a lot of them very verbose, and examples, when present, near the end. Options are often listed in alphabetic order, which doesn't usually correspond to how often they are used or useful. Man pages are OK when you're first learning how to use something; but if you're already familiar with a command and just need to remind yourself of a the specific sequence of options to achieve a desired result, they're not the most convenient. I think it's useful to have a tool that fulfills the latter purpose without worrying about the former.
  - JdeBP 10y ago
    Microsoft documentation was mentioned earlier in this discussion. One of the things that MSDN and TechNet doco does is have both "X reference" and "using X" sections. Manual pages are reference doco, in this way of organizing things. The FreeBSD, TrueOS, and related worlds put the "using" doco into what are often called "handbooks" or "guides". * NetBSD Guide: https://netbsd.org/docs/guide/en/ https://netbsd.org/docs/guide/en/ * FreeBSD Handbook: https://freebsd.org/doc/handbook/book.html https://freebsd.org/doc/handbook/book.html * DragonFlyBSD Handbook: https://www.dragonflybsd.org/docs/handbook/ https://www.dragonflybsd.org/docs/handbook/ * TrueOS User Guide: https://www.trueos.org/handbook/trueos.html https://www.trueos.org/handbook/trueos.html * PC-BSD User Guide: http://web.pcbsd.org/doc-archive/10.1.2/html/pcbsd.html http://web.pcbsd.org/doc-archive/10.1.2/html/pcbsd.html (viewable off-line directly in both PDF and HTML forms in /usr/local/share/pcbsd/doc/) Some parts of the Linux world do the same. upstart had the Upstart Cookbook for example: * http://upstart.ubuntu.com/cookbook/ http://upstart.ubuntu.com/cookbook/ The Linux Documentation Project was supposed to contain a wealth of this stuff, but large parts of it are seemingly moribund, and incomplete after decades or woefully outdated. Wikibooks tried to take up the slack with an "anyone can edit" Guide to Unix and a Linux Guide: * https://en.wikibooks.org/wiki/Guide_to_Unix https://en.wikibooks.org/wiki/Guide_to_Unix * https://en.wikibooks.org/wiki/Linux_Guide https://en.wikibooks.org/wiki/Linux_Guide If you want examples and doco that works from the basis of what you usually want to do, then these handbooks and guides are the places to go, not reference manuals.

teddyh 10y ago

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}} } Usage: $ 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 $

eriknstr 10y ago
Here's mine: examples () { man $1 | less +/^EXAMPLES } Usage: $ examples su EXAMPLES su -m man -c catman Starts a shell as user man, and runs the command catman. You will be asked for man's password unless your real UID is 0. Note that the -m option is required since user “man” does not have a valid shell by default. In this example, -c is passed to the shell of the user “man”, and is not interpreted as an argument to su. su -m man -c 'catman /usr/share/man /usr/local/man' Same as above, but the target command consists of more than a single word and hence is quoted for use with the -c option being passed to the shell. (Most shells expect the argument to -c to be a single word). su -m -c staff man -c 'catman /usr/share/man /usr/local/man' Same as above, but the target command is run with the resource limits of the login class “staff”. Note: in this example, the first -c option applies to su while the second is an argument to the shell being invoked. su -l foo Simulate a login for user foo. su - foo Same as above. su - Simulate a login for root.
- teddyh 10y ago
  You probably still want the MAN_KEEP_FORMATTING=1 part, to keep colorization and bolding etc. in the manual page. Also, your solution does not respect the user’s pager preference; the user might prefer to read man pages in “w3m”, for instance.