51 ms·

No. 90% of the time, I know what I want to do, and how my tools work. I just don't remember the options are called. Having a summary of the options right there

by ori_b 10y ago

No. 90% of the time, I know what I want to do, and how my tools work. I just don't remember the options are called. Having a summary of the options right there at the top is the most valuable thing in a reference.

gpvos 10y ago
For that there is the --help option.
- bluejekyll 10y ago
  And for this implementing cli, I've found http://docopt.org http://docopt.org to be an excellent and simple way to provide standard options and docs easily.
- anjbe 10y ago
  In practice --help output is mostly useless—it’s neither simple enough for a quick overview nor comprehensive enough to actually know what I can do. Tried “less --help” lately? It spits out ten pages of output! Plus, every program does --help differently. Does it spit out short output or tons of output so that I need a pager? Does it fork and execute a pager itself, or do I have to run the program again and pipe it to less manually? And then it turns out some programs print --help output to stderr, not stdout, so the pager doesn’t display any output until I do “blahblah --help 2>&1 | less”. A good manpage beats --help all hollow. It’s simultaneously more brief and more (usefully) verbose. The Synopsis section provides a quick overview of flags, if I just need a quick reminder to jog my memory. But if I want to know the details of a particular flag, I can just scroll down to it or search for it. Mandoc, the default manpage formatter in OpenBSD, even has semantic search built in. It uses more(1)'s built‐in tags functionality to take me straight to whatever flag I want. (You can get this functionality on Linux too by installing mandoc: http://mdocml.bsd.lv/ http://mdocml.bsd.lv/) Really, horrendous and arcane manpages are a trope that mostly exists in the Linux/GNU world. In BSDs, especially OpenBSD and FreeBSD, clear, simple documentation is a priority. No need for --help or “bropages” when the actual manpages are perfectly clear. For example, check out OpenBSD’s signify(1) manual (http://man.openbsd.org/signify.1 http://man.openbsd.org/signify.1), used for cryptographic signing and verification. Compare that to the monstrosity that is gpg(1)… (https://www.gnupg.org/documentation/manpage.en.html https://www.gnupg.org/documentation/manpage.en.html)
derefr 10y ago
You're presuming man pages are primarily meant to serve as a reference. But I rarely need man-pages as a reference†. Most of the time, if I'm looking up a man-page for something, it's because I've just installed a new package that sounded like it would solve a problem and then did a dpkg-query(1) to find out what binaries came with it—or used apropos(1) to find a relevant binary already installed—and now I want to know what the uses of a given binary are and whether those uses include solving my particular problem. † Well, except for the utilities with absolutely horrible command-line UX-design, like tar(1) or ps(1) or rsync(1), where I just memorize the options I need for my usual case, and then have to look in the man page to do anything novel.
- qwertyuiop924 10y ago
  >You're presuming man pages are primarily meant to serve as a reference. They are.
  - derefr 10y ago
    Let me rephrase: you assume that it makes sense for manpages to continue serving primarily as a reference—that this is the primary use-case people have for the standardized program documentation that ships with their distro packages. Shipping a reference to a binary with that binary may have made sense before the internet. But nowadays, it's the opposite. • Complex programs with many options have (sometimes dozens of) websites documenting them thoroughly. (Try searching with any search-engine for "wget mirroring", for example; the number and complexity of the results is overwhelming.) • Meanwhile, for the simple "corner-case" programs, you really hope that they shipped with docs—because seemingly nobody else out there on the web cares to bother documenting them. With a lot of these little programs, the only web doc you can find are, in fact, online mirrors of their man-page. For the popular-and-complex programs, man-pages are just redundant, because everyone will document what they did to achieve whatever. But for the simple-but-weird programs—the ones for which man-pages aren't just redundancies—if the man-page doesn't give usage, then nothing is going to give usage. Now, I can understand why man-pages for these little utilities are the way they are. These programs are usually created by a single author, so time spent writing docs is time not spent fixing bugs or scratching their itch or whatever else. And an options reference certainly is the "minimal normalized form" of documentation: it lets others brute-force combinatoric-search the space of invocations until they find some combination that Works For Them™. Basically, you can (through a lot of trial and error) generate a cookbook from an options reference. So the author probably doesn't feel a strong need to add anything beyond an options reference, because the people who really need to solve the problem their binary solves are willing to go to that effort. But if you're a distro downstream packager, and it's your job to make your distro easy for people to use, you should have every incentive to submit upstream patches to said author, with manpage additions of cookbook example usages resulting from your trial-and-error experimentation with their program. Annoyingly, you, as a distro packager, probably don't have time to do that trial-and-error experimentation, especially if the utility serves a niche use-case that you don't even understand. That—and not the fact that "manpages should be a reference and nothing more"—is most of the reason manpages continue to be the way they are.

by ori_b 10y ago

gpvos 10y ago

For that there is the --help option.

bluejekyll 10y ago
And for this implementing cli, I've found http://docopt.org http://docopt.org to be an excellent and simple way to provide standard options and docs easily.
anjbe 10y ago
In practice --help output is mostly useless—it’s neither simple enough for a quick overview nor comprehensive enough to actually know what I can do. Tried “less --help” lately? It spits out ten pages of output! Plus, every program does --help differently. Does it spit out short output or tons of output so that I need a pager? Does it fork and execute a pager itself, or do I have to run the program again and pipe it to less manually? And then it turns out some programs print --help output to stderr, not stdout, so the pager doesn’t display any output until I do “blahblah --help 2>&1 | less”. A good manpage beats --help all hollow. It’s simultaneously more brief and more (usefully) verbose. The Synopsis section provides a quick overview of flags, if I just need a quick reminder to jog my memory. But if I want to know the details of a particular flag, I can just scroll down to it or search for it. Mandoc, the default manpage formatter in OpenBSD, even has semantic search built in. It uses more(1)'s built‐in tags functionality to take me straight to whatever flag I want. (You can get this functionality on Linux too by installing mandoc: http://mdocml.bsd.lv/ http://mdocml.bsd.lv/) Really, horrendous and arcane manpages are a trope that mostly exists in the Linux/GNU world. In BSDs, especially OpenBSD and FreeBSD, clear, simple documentation is a priority. No need for --help or “bropages” when the actual manpages are perfectly clear. For example, check out OpenBSD’s signify(1) manual (http://man.openbsd.org/signify.1 http://man.openbsd.org/signify.1), used for cryptographic signing and verification. Compare that to the monstrosity that is gpg(1)… (https://www.gnupg.org/documentation/manpage.en.html https://www.gnupg.org/documentation/manpage.en.html)

derefr 10y ago

You're presuming man pages are primarily meant to serve as a reference. But I rarely need man-pages as a reference†. Most of the time, if I'm looking up a man-page for something, it's because I've just installed a new package that sounded like it would solve a problem and then did a dpkg-query(1) to find out what binaries came with it—or used apropos(1) to find a relevant binary already installed—and now I want to know what the uses of a given binary are and whether those uses include solving my particular problem. † Well, except for the utilities with absolutely horrible command-line UX-design, like tar(1) or ps(1) or rsync(1), where I just memorize the options I need for my usual case, and then have to look in the man page to do anything novel.

qwertyuiop924 10y ago
>You're presuming man pages are primarily meant to serve as a reference. They are.
- derefr 10y ago
  Let me rephrase: you assume that it makes sense for manpages to continue serving primarily as a reference—that this is the primary use-case people have for the standardized program documentation that ships with their distro packages. Shipping a reference to a binary with that binary may have made sense before the internet. But nowadays, it's the opposite. • Complex programs with many options have (sometimes dozens of) websites documenting them thoroughly. (Try searching with any search-engine for "wget mirroring", for example; the number and complexity of the results is overwhelming.) • Meanwhile, for the simple "corner-case" programs, you really hope that they shipped with docs—because seemingly nobody else out there on the web cares to bother documenting them. With a lot of these little programs, the only web doc you can find are, in fact, online mirrors of their man-page. For the popular-and-complex programs, man-pages are just redundant, because everyone will document what they did to achieve whatever. But for the simple-but-weird programs—the ones for which man-pages aren't just redundancies—if the man-page doesn't give usage, then nothing is going to give usage. Now, I can understand why man-pages for these little utilities are the way they are. These programs are usually created by a single author, so time spent writing docs is time not spent fixing bugs or scratching their itch or whatever else. And an options reference certainly is the "minimal normalized form" of documentation: it lets others brute-force combinatoric-search the space of invocations until they find some combination that Works For Them™. Basically, you can (through a lot of trial and error) generate a cookbook from an options reference. So the author probably doesn't feel a strong need to add anything beyond an options reference, because the people who really need to solve the problem their binary solves are willing to go to that effort. But if you're a distro downstream packager, and it's your job to make your distro easy for people to use, you should have every incentive to submit upstream patches to said author, with manpage additions of cookbook example usages resulting from your trial-and-error experimentation with their program. Annoyingly, you, as a distro packager, probably don't have time to do that trial-and-error experimentation, especially if the utility serves a niche use-case that you don't even understand. That—and not the fact that "manpages should be a reference and nothing more"—is most of the reason manpages continue to be the way they are.