Hacker News Reader

Comment by beefield | Hacker News Reader

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

View on HN

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.

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.

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

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

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 /^[^ ]

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

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

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.

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.

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 /^[^ ]

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.

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

Reply on news.ycombinator.com