4 ms·
These are some pretty good guidelines! Many thanks to the authors for writing them up. Some nitpicks (what would HN be without nitpicks?): > If your command i
by woodruffw 6y ago
These are some pretty good guidelines! Many thanks to the authors for writing them up.
Some nitpicks (what would HN be without nitpicks?):
> If your command is expecting to have something piped to it and stdin is an interactive terminal, display help immediately and quit.
I disagree with this advice: being able to spoon-feed input into a program is extremely useful, and is part of the "conversational" CLI paradigm that the authors mention above. Commands that silently block on `stdin` are frustrating, but the right solution is to check `isatty(3)` and print an informational message rather than killing the program entirely.
> Check general-purpose environment variables for configuration values when possible
Consider adding `$IFS` to this! Commands that support different output models based on `isatty(3)` often neglect to support `$IFS`, making them more difficult to use in pipelines. This is especially handy in pipelines that need to deal with messy or untrusted inputs; I regularly use `IFS` with the ASCII field escape bytes.
> Don’t bother with man pages.
Please do bother with them! Nobody needs to write raw roff or troff in 2020; there are plenty of high quality manpage generators[1][2][3] that will turn your Markdown/ReST/whatever documentation into sensibly formatted manpages. manpages are much easier to search than the medley of pseudo-formats that CLI tools choose to render their `--help` outputs with.
[1]: https://github.com/rtomayko/ronn https://github.com/rtomayko/ronn
[2]: https://pandoc.org/ https://pandoc.org/
[3]: https://www.sphinx-doc.org/en/1.4/man/sphinx-build.html https://www.sphinx-doc.org/en/1.4/man/sphinx-build.html
- hamburglar 6y ago> being able to spoon-feed input into a program is extremely useful, and is part of the "conversational" CLI paradigm that the authors mention above. Commands that silently block on `stdin` are frustrating, but the right solution is to check `isatty(3)` and print an informational message rather than killing the program entirely This was the one thing I was coming here to nitpick. I use the "blocking stdin" behavior regularly to pipe copy/pasted text through various commands (various openssl subcommands, for example) and would be very annoyed if a program decided on its own that I shouldn't be doing that. At most, it should print a message like "Reading from stdin..." or something on stderr, but even that seems like introducing noise to hold the hands of people who don't understand the pipe paradigm.
- matt_kantor 6y agoThese would probably get more attention if submitted to the issue tracker: https://github.com/cli-guidelines/cli-guidelines/issues https://github.com/cli-guidelines/cli-guidelines/issues
- cyberdelica 6y agoThe man macros for roff/troff/groff are not even particulary complicated. Anyone with half an hour to spend learning them, could write a man page without needing additional tools.
- woodruffw 6y agoI agree with this (and I maintain a bunch of manual troff, in both senses of the word "manual"), but I also think it isn't the point: the point is that you don't need to learn an additional markup/macro language to produce high-quality manpages. IME, the tools that are missing nice manpages are less than a decade old and have very good online documentation, particularly in the form of community-assisted ReST or Markdown docs. Most projects would rather just compile those docs into another format than introduce a split maintenance load for manpages.