4 ms·

I'm baffled all the time by the lack of clear examples on many manpages.

by huskyr 15y ago

malone 15y ago
Same here, most man pages seem pretty good at documenting all the available options, but are pretty useless at explaining how the tool should actually be used. I'd like to see someone dump all the common man pages into a public wiki so people could flesh out the usage examples and suggest alternative tools.
morsch 15y ago
Yep, a short list of useful one-liners would go a long way. Often, your use-case will be a straight specialisation of one of the examples, and if not, chances are you can cobble together something from several examples. I'd like to have a auxiliary help command for this, e.g. example ffmpeg in addition to man ffmpeg (another 18k words manpage). Edit: This works rather well: function cmdfu() { curl "http://www.commandlinefu.com/commands/matching/$@/$(echo -n $@ | openssl base64)/plaintext" --silent | sed "s/$^#.*$/\x1b[32m\1\x1b[0m/g" } From http://www.commandlinefu.com/commands/view/3086/search-commandlinefu.com-from-the-command-line-using-the-api#comment http://www.commandlinefu.com/commands/view/3086/search-comma..., it uses the commandlinefu API: http://www.commandlinefu.com/site/api http://www.commandlinefu.com/site/api
- JonWood 15y ago
  Another alternative is <a href="http://cheat.errtheblog.com/>Cheat</a> http://cheat.errtheblog.com/>Cheat</a>, which is essentially a CLI accessible wiki of usage examples. It was originally focused on Ruby (and still is to an extent), but it gives decent results a lot of the time.
slug 15y ago
yes, bring back the VAX/VMS help system with the helpful examples at the end, was awesome last time I used it.
dredmorbius 15y ago
There is a standard "EXAMPLES" section to manpages. It's just not used often enough. Most Linux distros have a bug reporting feature which could be used to suggest such examples, and it would be a Good Thing if more were suggested.
Nick_C 15y ago
You could try the OpenBSD man pages. One of OpenBSD's must-haves is good documentation. If I'm looking for an example and the Linux man doesn't have one, I'll often google for "openbsd man xxxx". Of course, watch out for differences in the utility. OpenBSD (usually) won't have any GNU extensions, for example.

I'm baffled all the time by the lack of clear examples on many manpages.

by huskyr 15y ago

I'm baffled all the time by the lack of clear examples on many manpages.

Same here, most man pages seem pretty good at documenting all the available options, but are pretty useless at explaining how the tool should actually be used. I'd like to see someone dump all the common man pages into a public wiki so people could flesh out the usage examples and suggest alternative tools.

morsch 15y ago

Yep, a short list of useful one-liners would go a long way. Often, your use-case will be a straight specialisation of one of the examples, and if not, chances are you can cobble together something from several examples. I'd like to have a auxiliary help command for this, e.g. example ffmpeg in addition to man ffmpeg (another 18k words manpage). Edit: This works rather well: function cmdfu() { curl "http://www.commandlinefu.com/commands/matching/$@/$(echo -n $@ | openssl base64)/plaintext" --silent | sed "s/$^#.*$/\x1b[32m\1\x1b[0m/g" } From http://www.commandlinefu.com/commands/view/3086/search-commandlinefu.com-from-the-command-line-using-the-api#comment http://www.commandlinefu.com/commands/view/3086/search-comma..., it uses the commandlinefu API: http://www.commandlinefu.com/site/api http://www.commandlinefu.com/site/api

JonWood 15y ago
Another alternative is <a href="http://cheat.errtheblog.com/>Cheat</a> http://cheat.errtheblog.com/>Cheat</a>, which is essentially a CLI accessible wiki of usage examples. It was originally focused on Ruby (and still is to an extent), but it gives decent results a lot of the time.

slug 15y ago

yes, bring back the VAX/VMS help system with the helpful examples at the end, was awesome last time I used it.

dredmorbius 15y ago

There is a standard "EXAMPLES" section to manpages. It's just not used often enough. Most Linux distros have a bug reporting feature which could be used to suggest such examples, and it would be a Good Thing if more were suggested.

Nick_C 15y ago

You could try the OpenBSD man pages. One of OpenBSD's must-haves is good documentation. If I'm looking for an example and the Linux man doesn't have one, I'll often google for "openbsd man xxxx". Of course, watch out for differences in the utility. OpenBSD (usually) won't have any GNU extensions, for example.