4 ms·

My usage of manpages would increase by orders of magnitude if I knew there were examples of actual working commands in the first page. Most of the time I am not

My usage of manpages would increase by orders of magnitude if I knew there were examples of actual working commands in the first page. Most of the time I am not looking for an obscure parameter, but my brain just has failed to take a note of the basic syntax of the command. So why not start ssh manpage with two simple examples, how to connect to a host with username and ssh key: ssh user@example.com ssh -i ~/.ssh/id_rsa user@example.com

sshagent 8y ago
indeed. I've always thought this, would be nice to see examples that might cover my need. Then read what the switches/options do.
- funklebunkle 8y ago
  So you're just going to run some command without knowing what it does, just because it looks right?
cygned 8y ago
That is the reason why I like the Golang documentation; it consists of exhaustive comments, (runnable) examples, explanatory code snippets and links to the corresponding source. Works as a reference but also for explorative learning.
dspillett 8y ago
There are a few projects out there trying to do this as community driven efforts or by extracting examples automatically from the existing man pages (or a mix of the two). https://tldr.sh/ https://tldr.sh/ and http://bropages.org/ http://bropages.org/ spring to mind, and I know there are others that I'm not immediately remembering ATM, both of which have web interfaces or can be installed as local command-line tools.
gumby 8y ago
This is how every man page starts, with a "SYNOPSIS" of invocation. For example the ssh man page starts: ssh [-46AaCfGgKkMNnqsTtVvXxYy] [-B bind_interface] [-b bind_address] [-c cipher_spec] ... If there are several incompatible ways to invoke an operation several cases are given, e.g. netstat [-AaLlnW] [-f address_family | -p protocol] netstat [-gilns] [-v] [-f address_family] [-I interface] ... Typically there are examples in the EXAMPLES or USAGE section which you can jump straight to via /^U or /^E In the case of ssh there are several such sections so just jump to them via /^[^ ]
- crispyambulance 8y ago
  > ssh [-46AaCfGgKkMNnqsTtVvXxYy] [-B bind_interface] [-b bind_address] [-c cipher_spec] ... That's exactly the kind of "SYNOPSIS" would make me want to stomp on puppies when looking at a man page because I forgot some basic usage. But actually, thanks for the key-combo tip on jumping straight to examples.
  - knolan 8y ago
    I find many manpages to be pretty obtuse. They could do a lot to help those of us who need a bit more hand holding. I like cheat.sh. You can curl it directly from your terminal and it offers the quick examples I often need to get back to work. Here is their ssh page: http://cheat.sh/ssh http://cheat.sh/ssh Also I am a huge fan of Matlab’s Documentation, at least up to the more recent versions that became less usable. They give a clear description of the function, list syntax options, give several examples and provide a see also section with similar or related functions (greatly helping discoverability). They usually include academic references at the end. https://uk.mathworks.com/help/matlab/ref/atand.html?s_tid=doc_ta https://uk.mathworks.com/help/matlab/ref/atand.html?s_tid=do...
  - gumby 8y ago
    Whereas it works great for me so that when I can’t remember the precise syntax I can just glance at the top of the man page; if I want anspecific option I can search for it. Info format files are intended to be more comprehensive and tutorial but they never really made the jump to Unix.
- beefield 8y ago
  Sorry, in my Ubuntu 18.04 "man ssh" produces output that does not have either EXAMPLES or USAGE. /^E takes me to ENVIRONMENT instrad of EXAMPLES.
  - gumby 8y ago
    Yes but as I mentioned in my comment for ssh there are several sections that each explain a different use case which you can jump to via /^[^ ]
tombrossman 8y ago
> My usage of manpages would increase by orders of magnitude if I knew there were examples of actual working commands in the first page. Try adding ManKier as a custom search provider for Firefox or Chrome, it is online man pages beginning with TL;DR examples at the top of each web page, followed by the traditional man page entry below. Here is a fuller explanation with links to instructions for adding it to your browser: https://www.mankier.com/about https://www.mankier.com/about I use it almost exclusively now, and only refer to my distro's man page in a terminal if I need to check on something that isn't standardised (such as sed -i.bak or something like that). Custom browser search is pretty handy, try adding a dictionary and map provider too, or 'caniuse' if you do front-end work.

sshagent 8y ago

indeed. I've always thought this, would be nice to see examples that might cover my need. Then read what the switches/options do.

funklebunkle 8y ago
So you're just going to run some command without knowing what it does, just because it looks right?

cygned 8y ago

That is the reason why I like the Golang documentation; it consists of exhaustive comments, (runnable) examples, explanatory code snippets and links to the corresponding source. Works as a reference but also for explorative learning.

dspillett 8y ago

There are a few projects out there trying to do this as community driven efforts or by extracting examples automatically from the existing man pages (or a mix of the two). https://tldr.sh/ https://tldr.sh/ and http://bropages.org/ http://bropages.org/ spring to mind, and I know there are others that I'm not immediately remembering ATM, both of which have web interfaces or can be installed as local command-line tools.

gumby 8y ago

This is how every man page starts, with a "SYNOPSIS" of invocation. For example the ssh man page starts: ssh [-46AaCfGgKkMNnqsTtVvXxYy] [-B bind_interface] [-b bind_address] [-c cipher_spec] ... If there are several incompatible ways to invoke an operation several cases are given, e.g. netstat [-AaLlnW] [-f address_family | -p protocol] netstat [-gilns] [-v] [-f address_family] [-I interface] ... Typically there are examples in the EXAMPLES or USAGE section which you can jump straight to via /^U or /^E In the case of ssh there are several such sections so just jump to them via /^[^ ]

crispyambulance 8y ago
> ssh [-46AaCfGgKkMNnqsTtVvXxYy] [-B bind_interface] [-b bind_address] [-c cipher_spec] ... That's exactly the kind of "SYNOPSIS" would make me want to stomp on puppies when looking at a man page because I forgot some basic usage. But actually, thanks for the key-combo tip on jumping straight to examples.
- knolan 8y ago
  I find many manpages to be pretty obtuse. They could do a lot to help those of us who need a bit more hand holding. I like cheat.sh. You can curl it directly from your terminal and it offers the quick examples I often need to get back to work. Here is their ssh page: http://cheat.sh/ssh http://cheat.sh/ssh Also I am a huge fan of Matlab’s Documentation, at least up to the more recent versions that became less usable. They give a clear description of the function, list syntax options, give several examples and provide a see also section with similar or related functions (greatly helping discoverability). They usually include academic references at the end. https://uk.mathworks.com/help/matlab/ref/atand.html?s_tid=doc_ta https://uk.mathworks.com/help/matlab/ref/atand.html?s_tid=do...
- gumby 8y ago
  Whereas it works great for me so that when I can’t remember the precise syntax I can just glance at the top of the man page; if I want anspecific option I can search for it. Info format files are intended to be more comprehensive and tutorial but they never really made the jump to Unix.
beefield 8y ago
Sorry, in my Ubuntu 18.04 "man ssh" produces output that does not have either EXAMPLES or USAGE. /^E takes me to ENVIRONMENT instrad of EXAMPLES.
- gumby 8y ago
  Yes but as I mentioned in my comment for ssh there are several sections that each explain a different use case which you can jump to via /^[^ ]

tombrossman 8y ago

> My usage of manpages would increase by orders of magnitude if I knew there were examples of actual working commands in the first page. Try adding ManKier as a custom search provider for Firefox or Chrome, it is online man pages beginning with TL;DR examples at the top of each web page, followed by the traditional man page entry below. Here is a fuller explanation with links to instructions for adding it to your browser: https://www.mankier.com/about https://www.mankier.com/about I use it almost exclusively now, and only refer to my distro's man page in a terminal if I need to check on something that isn't standardised (such as sed -i.bak or something like that). Custom browser search is pretty handy, try adding a dictionary and map provider too, or 'caniuse' if you do front-end work.