4 ms·

One trend I've really not appreciated in recent years is neglecting man pages for command line utilities. Having a `--help` option is great as a cheat sheet, b

One trend I've really not appreciated in recent years is neglecting man pages for command line utilities. Having a `--help` option is great as a cheat sheet, but nowadays these help outputs are much too large and hard to navigate because. Alongside complete man pages, help commands can be helpful high level overviews focusing on common use cases with examples.

ams6110 10y ago
Thanks for saying this, I was about to say the same thing. Write a man page. --help or -? is OK for a terse summary but don't put detailed instructions in --help output, because then I have to run it twice (since I didn't add '| less' the first time).
dredmorbius 10y ago
That's been a long-standing beef of mine for well over a decade. There are several apparent sources of this. The GNU project deprecates man in favour of info. This is a category error for numerous reasons. The good news is that the documentation still exists, man can be configured to fall back to 'pinfo' or similar, and projects (Debian are particularly good about this) can schlep the Info format into a manpage. There's an argument in favour of info: it was a hypertext document format which is, arguably, more powerful than man. On the other hand, it has a format-specific reader (info), there's a far more dominant hypertext document format (HTML), and there are utilities to provide manpages in HTML format and over a local HTML server (dwww:https://packages.debian.org/stable/doc/dwww https://packages.debian.org/stable/doc/dwww). GNU should have bailed on this decades ago. Several projects, notably GNOME (a GNU project) and many Red Hat utilities, lack good / updated / any manpages. This is particularly frustrating. KDE similarly fails frequently to provide manpages. Again, Debian frequently will create and provide manpages, but they will frequently run behind package development, so new features aren't clearly documented. Increasingly, standalone packages (say, imagemagick) don't fully document themselves in manpages. Worse are vendor utilities which lack any manpage, a useful --help or -? -h page, or anything else vaguely resembling sane practices. This is entirely inexcuseable.
restalis 10y ago
Maybe including dependent switches to enable/disable different parts of shown information? For example just "--help" would show a short description and the existing switches for further debriefing. Then you'll have to type "--help --commands" for showing a list of commands and description in one or two words, or "--help --examples" to show a whole lot of examples, and so on.
eichin 10y ago
Write a man page, but it's 2016, you don't have to write it in ROFF... It got a lot easier to get people to write or update man pages for a bunch of in-house CLI tools when I found ronn https://rtomayko.github.io/ronn/ https://rtomayko.github.io/ronn/ which starts from markdown (you'll still get a lot of copy/paste formatting from your other man pages but at least it'll be readable.)

ams6110 10y ago

Thanks for saying this, I was about to say the same thing. Write a man page. --help or -? is OK for a terse summary but don't put detailed instructions in --help output, because then I have to run it twice (since I didn't add '| less' the first time).

dredmorbius 10y ago

That's been a long-standing beef of mine for well over a decade. There are several apparent sources of this. The GNU project deprecates man in favour of info. This is a category error for numerous reasons. The good news is that the documentation still exists, man can be configured to fall back to 'pinfo' or similar, and projects (Debian are particularly good about this) can schlep the Info format into a manpage. There's an argument in favour of info: it was a hypertext document format which is, arguably, more powerful than man. On the other hand, it has a format-specific reader (info), there's a far more dominant hypertext document format (HTML), and there are utilities to provide manpages in HTML format and over a local HTML server (dwww:https://packages.debian.org/stable/doc/dwww https://packages.debian.org/stable/doc/dwww). GNU should have bailed on this decades ago. Several projects, notably GNOME (a GNU project) and many Red Hat utilities, lack good / updated / any manpages. This is particularly frustrating. KDE similarly fails frequently to provide manpages. Again, Debian frequently will create and provide manpages, but they will frequently run behind package development, so new features aren't clearly documented. Increasingly, standalone packages (say, imagemagick) don't fully document themselves in manpages. Worse are vendor utilities which lack any manpage, a useful --help or -? -h page, or anything else vaguely resembling sane practices. This is entirely inexcuseable.

restalis 10y ago

Maybe including dependent switches to enable/disable different parts of shown information? For example just "--help" would show a short description and the existing switches for further debriefing. Then you'll have to type "--help --commands" for showing a list of commands and description in one or two words, or "--help --examples" to show a whole lot of examples, and so on.

eichin 10y ago

Write a man page, but it's 2016, you don't have to write it in ROFF... It got a lot easier to get people to write or update man pages for a bunch of in-house CLI tools when I found ronn https://rtomayko.github.io/ronn/ https://rtomayko.github.io/ronn/ which starts from markdown (you'll still get a lot of copy/paste formatting from your other man pages but at least it'll be readable.)