6 ms·
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-
by 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 agoLet 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.
- ktRolster 10y agoMan pages are written (ideally) as the authoritative reference on your system, where you can go to find information. That sort of thing needs to exist somewhere, it has a clear use case. An ideal man page is concise, informative, and complete. Learning to read them is like learning to read scientific literature: a pain, but once you figure it out, you're at a higher level.
- qwertyuiop924 10y ago>you assume that it makes sense for manpages to continue serving primarily as a reference No, I don't. But that's what they are, and what they're meant to be. Complaining that they are is like complaining that Haskell is functional: It may not be ideal for your circumstances, and you're welcome to make that known, but there's no use complaining about it, because it's the entire point.
- Hello71 10y ago> absolutely horrible command-line UX-design, like tar(1) or ps(1) or rsync(1) how would you improve their design
- derefr 10y ago• The primary win for all of those utilities would be in separating their horribly-large arrays of top-level runtime switches into subcommands that each have a restricted, learnable set of runtime switches relevant only to that subcommand. (See: git, docker, lvm, ip, ufw). • As well, for top-level switches that are really preferences—that is, switches that don't apply to a use-case, but rather to a user—read those from ~/.config/foo/foorc with defaults in /etc/foo/foorc. Don't expose them at all as runtime switches. If there are features that would be customized by different wrapper-client UIs, provide a --config-file=[file] switch that takes a config-file that sets those. And for special drivers, like Makefiles or CI setups, that have a matrix of different UI options they might want to ask for, you can provide FOO_OPTION env-vars. (See: curl, compiler toolchains, ffmpeg, apt). In ffmpeg's case, there are even config-file presets—basically little plug-ins of config options you can enable as a group. You can dump new files into the /etc/ffmpeg/presets or ~/.config/ffmpeg/presets to add them as presets. • For switches that are exposed individually, but which are also aggregated into switch-group-setting switches, in most cases there's literally no use-case for setting the individual switches, only the switch-group-setting switch. Remove the individual switches. Just because the program could theoretically be configured to do X compatibility thing for old-arch Foo, but not Y other old compatibility thing for old-arch Foo (where any time you're talking to Foo you always need both), you don't have to expose both an X switch and a Y switch. Just expose a --foo-compat switch and be done with it. People trying to use your binary on other weird OSes shouldn't be doing so by combining tons of option-switches; they should sit down and port your program to that OS, by finding the place in your program where you've defined {arch -> shim flag set} mappings, adding a new mapping for their arch, and exposing it as a new external --bar-compat switch. • Speaking of compat flags, try just making such behaviors always-on when you build targeting the relevant arch, rather than needing to specify them at runtime. The only real use-case for runtime compat switches is as an IPC/RPC client talking to a server that expects the weird behaviour. And even then, your client should first try to auto-detect the server's expectations, and you should only add the runtime switch if that auto-detection turns out to be unreliable. (Meanwhile, If you're the IPC/RPC server, the compat settings belong in the config file. See: Samba, NFS, Netatalk, ...) • If your binary manipulates state (like, say, how git manipulates repos), and you change the way it does so in a backward-incompatible manner, you might be tempted to add a runtime switch to turn the old behaviour back on to allow collaboration with people using older versions. If your state-store is at all extensible, though, you should instead add a field for a schema-version and a flag for pinning the state-store to that schema-version, as well as a subcommand to pin/unpin a given state-store's schema-version. Now your binary will upgrade the schema of its state-store by default, but will respect "protected" state-stores and perform only backward-compatible operations on those. (Importantly, this guides the code architecture into failing by default instead of doing something backward-incompatible; whereas, with backcompat switches, you're always forcing a state-store schema-migration on people by default every time you add new code, unless/until you add a matching backcompat-switch.) • quiet/verbose and interactive/batch are silly "mode switches" to have in modern programs, just like forking is a silly way to do daemons when you've got a modern init(8). Put interactively-useful information on stdout, and do interactive prompting, if-and-only-if isatty(STDIN); put information of all levels of usefulness on syslog with appropriate error-level tags attached. It's up to the thing running your program to provide a PTY or not, and to filter your output or not. Be friendly to expect(1). These guidelines together should trim each subcommand to a reasonable "visible" option-set. Now just ensure that typing "man command subcommand" gets you a separate man-page written just for the subcommand, and add bash/zsh completion for each subcommand and for the subcommands list itself.