4 ms·
I almost stopped reading at "I would skip man pages", but the rest of the article was mostly great advice. I disagree about 11 (using "main_command sub_command
by gnomewascool 8y ago
I almost stopped reading at "I would skip man pages", but the rest of the article was mostly great advice.
I disagree about 11 (using "main_command sub_command:sub-sub_command" rather than "main sub sub-sub" syntax), but it's mostly a matter of taste.
Seriously, though, if you've already taken the time to write documentation, then there's no reason not to also generate a manpage. Just using pandoc to convert your, say, README.md gives good-enough results:
pandoc -s -f markdown_github -t man -o your_cli.1 README.md
(There probably are other good conversion methods.)
Why I like man:
Advantage over online docs:
It's offline and available directly in the terminal, without having to open a browser and it has a distraction-free, clean look. The only slight disadvantage is the lack of support for images, which are occasionally helpful, but in a pinch, for some use-cases, you can have ascii diagrams.
Advantages over "--help":
1. Conventionally, "--help" just provides a brief rundown/reminder of the options, so having full documentation is valuable.
2. If "--help" provides the full docs then:
a) You lose the option of having the brief rundown, which is also very valuable.
b) "man command" is slightly faster than "command --help" :p (yes, it is a slight pity that accessing the full docs is faster than accessing the brief version, if you use convention).
c) man deals with things like having nice output, with proper margins, at different terminal widths.
d) man deals with the formatting for you, providing consistency with all other applications.
FWIW I think that texinfo is (mostly) even better than man, as it considerably improves on the navigation, but it's been crippled by the FSF-Debian GFDL feud, which meant that the info pages weren't actually installed on many systems, and it's mostly a lost cause now.
- enriquto 8y ago> Advantages of man over "--help": You can have the best both worlds if the manpages are built automatically from the "--help" output (e.g., using help2man). Then you can have "-h" give a brief rundown and "--help" give the full docs. > FWIW I think that texinfo is (mostly) even better than man, as it considerably improves on the navigation I am curious about that. Do you really like texinfo navigation? I find it completely unusable, to the point of prefering to download and print a pdf from the web instead of opening (gasp!) the dreaded "info" program.
- TeMPOraL 8y agoI use info browser from Emacs and like it very much. The best benefit is that you can stuff a whole book into info pages - and projects using info usually drop their full manual in there, to be perused off-line and distraction-free.
- enriquto 8y agoHow do you search for a word inside the whole info documentation of a program (say, gcc), and cycle through all appearances of that word? I never managed to do that (which is trivial for manpages).
- jwilk 8y agoTypographical quality of automatically generated manpages is usually very poor. Also, I expect man pages to be more detailed than --help.
- dickeytk 8y agoYou could have a `--full` or `--verbose` flag on the help command to display the full output. That will work on Windows as well.
- a_e_k 8y agoOne style that I've seen that I really like is having the help system be its own first-class subcommand. E.g., just `p4 help` gives you the quick summary with a list of available subcommands, then something like `p4 help filelog` gives you the details on just the filelog subcommand. I find that this avoids the problem of a having a single help spiel that is either too brief or too verbose to be useful. (The article sort of touches on this with mention of `mycli subcommand --help` as something that should show help and `mycli subcommand help` as potentially confusing `help` with an argument. But I find that making help a full subcommand tends to avoid avoid this ambiguity. And having the bare help command give the table of contents lends structure to the help system.)
- dickeytk 8y agoperhaps I should've called this out explicitly, but yes, I would expect a CLI to do this. I have future plans for oclif to take this a step further and make the help contextual based on what you're working with. For example, if you wanted to see what commands might relate to a file you might get different commands than a directory.