3 ms·
"common denominator" is the thing that is guaranteed common for all commands. man(1) is, provided that people produce man pages. It's also orthogonal and compo
by lloeki 2y ago
"common denominator" is the thing that is guaranteed common for all commands.
man(1) is, provided that people produce man pages. It's also orthogonal and composable without interference: one can write a man page for commands that don't have man pages.
Flags are not, because commands parse their arguments in whatever way; all commands can accept arguments but arguments are also part of the operational interface contract. man(1) is decoupling all possible problems out.
It is also extremely obvious than `man foo` is side-effect free, whereas `foo whatever`, whether `whatever` can be `--help` or anything else, has unknown effects when the command is unknown.
Some argue that man pages are too rich; well the man pages can just also start with a summary identical to what a hypothetical `--help` flag would output.
Turns out this is the conventional `SYNOPSYS` title of section 1 man pages, and possibly the `OPTIONS` one; if these are absent or badly written then one could reasonably posit that a hypothetical `--help` flag output would be just as unhelpful; cue the wads of commands that "--helpfully" output `foo [-4236xXksirtTgsdv]` as help, which tells you nothing really helpful.
`info(1)` can burn in hell though.
- maleldil 2y agoMy understanding is the opposite: man pages are much more difficult to produce than plain help text, so it's unreasonable to expect they'll always be available, while help is easy enough to (almost) always be there. If you use any CLI library at all, it will automatically be generated. If you don't, the equivalent of `argv[1] == "--help"` is good enough. These days, I'm positively surprised when I find man pages for a program, whereas I'm annoyed when one doesn't support --help.
- lloeki 2y ago> man pages are much more difficult to produce than plain help text They're absolutely trivial to generate these days, gone are the days of having to deal with roff, you can write a quite dumb markdown file and produce a man page out of it in short order. https://github.com/sunaku/md2man/blob/master/EXAMPLE.markdown https://github.com/sunaku/md2man/blob/master/EXAMPLE.markdow... https://github.com/rtomayko/ronn/blob/master/man/ronn-format.7.ronn https://github.com/rtomayko/ronn/blob/master/man/ronn-format...
- maleldil 2y agoI'm not necessarily saying they're _difficult_, but it should be obvious they're relatively harder. For --help, the least I could do would be a conditional at the top of the program, or let my CLI library auto-generate it for me. For man pages, I have to go out of my way to explicitly generate and distribute them.
- TeMPOraL 2y ago> Some argue that man pages are too rich There are people arguing that? My feeling is that man pages are usually so thin as to be useless in 50%+ scenarios I need them. I really wished the culture defaulted to expecting all software to come with Info pages.