News for hackers. Stuff that matters.
Re:SSH Examples, Tips and Tunnels by beefield on Friday December 28, 2018 @07:52AM (#18776451)
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 [email protected]

ssh -i ~/.ssh/id_rsa [email protected]

Re:SSH Examples, Tips and Tunnels by cygned on Friday December 28, 2018 @09:22AM (#18776827)
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.

Re:SSH Examples, Tips and Tunnels by dspillett on Friday December 28, 2018 @09:37AM (#18776910)
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/ and 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.

Re:SSH Examples, Tips and Tunnels by sshagent on Friday December 28, 2018 @09:06AM (#18776749)
indeed. I've always thought this, would be nice to see examples that might cover my need. Then read what the switches/options do.
Re:SSH Examples, Tips and Tunnels by funklebunkle on Friday December 28, 2018 @09:28AM (#18776861)
So you're just going to run some command without knowing what it does, just because it looks right?
Re:SSH Examples, Tips and Tunnels by gumby on Friday December 28, 2018 @11:59AM (#18777904)
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 /^[^ ]

Re:SSH Examples, Tips and Tunnels by crispyambulance on Friday December 28, 2018 @12:10PM (#18777964)

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

Re:SSH Examples, Tips and Tunnels by knolan on Friday December 28, 2018 @12:46PM (#18778208)
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

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

Re:SSH Examples, Tips and Tunnels by gumby on Friday December 28, 2018 @08:57PM (#18781218)
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.

Re:SSH Examples, Tips and Tunnels by beefield on Friday December 28, 2018 @12:48PM (#18778217)
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.
Re:SSH Examples, Tips and Tunnels by gumby on Friday December 28, 2018 @03:51PM (#18779318)
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 /^[^ ]
Re:SSH Examples, Tips and Tunnels by beefield on Saturday December 29, 2018 @02:30AM (#18782473)
Sorry, I am confused. In your comment you said that in case of ssh there are several EXAMPLES or USAGES sections. Well, in my case I find exactly zero instances regardless what kind of key combo from your comment I use.

If you instead meant that e.g. TCP FORWARDING or X11 FORWARDING are such sections that explain use cases, well, in that case I still fail to find a section that would describe simple use case of just connecting to a host.

Re:SSH Examples, Tips and Tunnels by tombrossman on Friday December 28, 2018 @02:50PM (#18778969)
> 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

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.