Hacker News Reader

Comment by throwaway201103 | Hacker News Reader

throwaway201103

Your CLI should also have a man page, installed in the standard way. IMO, -? or --help should be fairly terse, ideally one screenful or less. More complete documentation should go in the man page.

Edit: wrote this before I read "Don’t bother with man pages." Strongly disagree. Relying on web docs leaves your users in the lurch if they are working on a system with no external network.

View on HN

> "Don’t bother with man pages." Strongly disagree.

Me too. I don’t want to jump to a different program, plus man pages are greppable. And you want the man pages that apply to the machine you’re using (versions, etc) — especially important when you’re using a remote machine (think how common then idiom is to do `ssh foo man blah|less` )

> "Don’t bother with man pages." Strongly disagree.

Me as well. Though I am not against well linked documentation on the web. But man pages provide several unique advantages.

- Because man pages are installed with the same package the software comes in, their version matches exactly to the version of the installed software.

- Man pages don't require an internet connection or a running server. The internet connection can be a problem in certain kinds of enterprise networks, embedded system or during my commute in the train. The running server costs money who might not be willing to spend it as long as I would like to use the software.

- Linking from the executable to the web is tricky. Does the terminal support clickable links? Which browser should I start? Does it help the user in any way to start a browser on a far away machine that he connected to through ssh, mosh, telnet or morse code over avian carrier?

- It is very easy and safe to open a man page to an unknown command. You can be sure the command is not executed by accident. If I have to type `some-command --help` I am never sure if this is one of those commands that doesn't accept --help and does something stupid instead.

Despite all these advantages of man pages or offline available documentation I also like good online documentation. https://www.postgresql.org/docs/current/ comes to my mind when thinking about excellent software documentation. Granted it is not a one-minute tutorial for the latest newbie. But for someone using that piece of software for years, its value cannot be overstated imho.

While I regularly rely on `man` (and would agree with you for systems that have it), I'd also like to add that you should consider people on other systems, as well.

I'm still stuck on Windows for work, and e.g. the way Git (at least the Windows version from git-scm.org) handles this is problematic.

Something like `git --help` will open the URL to a help page (that also takes ages to load) in the browser. Manpages don't exist and there is no useful substitute. And this in a Git distribution that ships with its own GNU environment (MSYS2). And then, there's Git LFS, for which I haven't even found a working help command yet.

While the original idea might have been that the terminal way of looking things up is too confusing for Windows users (which I find ironic, given that said users installed a terminal program), I find it still makes Git even more arcane on this platform.

Edit: Coming back to `man`: Git is in the useful position of shipping their own GNU environment. That means, they could still introduce manpages. Other, small CLI utilities usually don't have that luxury. In those cases, some kind of access to the information in the manpage would still be very handy, even if it is just in `tool --help`.

Pandoc has the ability to output manpages from .md or .rst documents, so if you already have a web version rendered from those, I see no reason not to include them. I absolutely love software with manpages and leaving them alone just because other platforms (or simply just Windows) don't have them is a bit of an insult.

Ouch. I don't know if anything changed on the last ~10 years, but opening .md files used to open start the Windows help, with an indexing window, that never ended. And if you waited long enough (could be hours), it would open a small fragment of your help, with a navigation that could lead only to the system help.

If Git on Windows can open a browser on a URL, why not just have that be a local HTML file? At least that works if there's a GUI and browser installed (rarely not the case on Windows, but if not you could include lynx and use that in the terminal as a fallback).

I think it does do that, actually. Definitely better in that it can be used without internet access, but I will admit that I have been guilty of thinking "if I'm going to be opening a browser anyway, might as well just google the question and get more targeted help."

I think (correct me if im wrong) tools shells like fish and zsh use the man pages to extract the param suggestions. That saves me so much time

Bash-completion does something like this for commands with consistent --help output (most Coreutils, bash, awk, grep, sed...) by parsing it in the completion function: https://github.com/scop/bash-completion/blob/29508ce70914f78...

I’ve been learning Perl lately, and was surprised and pleased to learn that the built-in pod2usage() functionality for converting POD documentation in your program into --help output also automatically supports manpage output. So the Perl programs I’ve been writing all include this as part of their arg-parsing loop:

  pod2usage(-verbose => 1) if /^(-h|--help)$/;
  pod2usage(-verbose => 2) if /^--man$/;

That second line is all it takes to produce a manpage too. Then it’s just a matter of writing the POD documentation for it.

It is admittedly a little unusual to consume a manpage by typing `someprog --man` instead of typing `man someprog`, but it’s very convenient for self-contained scripts.

I write docs as a plain text file (in /usr/share/doc), works everywhere, view with anything in any way you want, locally or in the web, no converters needed.

Reply on news.ycombinator.com