CLI Guidelines – A guide to help you write better command-line programs • Hacker News Board

Re: CLI Guidelines – A guide to help you write better command-line programs

#151

Post by marcosdumay » Sat, Dec 05, 2020, 7:51 PM UTC

enedil wrote: post #125

btschaegg wrote: post #112

Earlier quoted context omitted.

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…

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.

Re: CLI Guidelines – A guide to help you write better command-line programs

#152

Post by bfirsh » Sat, Dec 05, 2020, 8:24 PM UTC

kitotik wrote: post #16

This is a great resource, thanks for the effort. I strongly disagree with the “ Don’t bother with man pages” advice. It’s extremely annoying when tools don’t provide a manpage. The overhead of opening up a browser to reference command is cumbersome and highly annoying. There are tools such as pandoc that make generating manpages from various source formats very easy. Perhaps it is just my grouchy old man syndrome…

The sentiment was meant to be: "Make `command help` as good as a man page. More people will read that." We didn't mean to suggest to use web pages instead.

We also didn't mean not to use man pages at all. We just find more people use the built-in help and web pages, so if you have limited time/resources, it's better spent on those things.

In retrospect, perhaps it was worded a bit strongly. I am enjoying the debate, though. The meta point, and part of the reason for this document to exist, is that perhaps it's a good idea to question our 30-year-old traditions and see if we can come up with better ways of doing things. This seems to have got people talking again. :)

Re: CLI Guidelines – A guide to help you write better command-line programs

#153

Post by [deleted] » Sat, Dec 05, 2020, 8:35 PM UTC

bfirsh wrote: post #152

kitotik wrote: post #16

This is a great resource, thanks for the effort. I strongly disagree with the “ Don’t bother with man pages” advice. It’s extremely annoying when tools don’t provide a manpage. The overhead of opening up a browser to reference command is cumbersome and highly annoying. There are tools such as pandoc that make generating manpages from various source formats very easy. Perhaps it is just my grouchy old man syndrome…

The sentiment was meant to be: "Make `command help` as good as a man page. More people will read that." We didn't mean to suggest to use web pages instead. We also didn't mean not to use man pages at all. We just find more people use the built-in help and web pages, so if you have limited time/resources, it's better spent on those things. In retrospect, perhaps it was worded a bit strongly. I am enjoying the debate,…

[deleted]

Re: CLI Guidelines – A guide to help you write better command-line programs

#154

Post by whirlwin » Sat, Dec 05, 2020, 8:41 PM UTC

The most important part for me when creating a new CLI is the ability for the end user to debug the CLI themselves and step through it. This is much easier with e.g. Python, but fairly more complex with a binary built by Go

Re: CLI Guidelines – A guide to help you write better command-line programs

#155

Post by indymike » Sat, Dec 05, 2020, 8:49 PM UTC

bfirsh wrote: post #152

kitotik wrote: post #16

This is a great resource, thanks for the effort. I strongly disagree with the “ Don’t bother with man pages” advice. It’s extremely annoying when tools don’t provide a manpage. The overhead of opening up a browser to reference command is cumbersome and highly annoying. There are tools such as pandoc that make generating manpages from various source formats very easy. Perhaps it is just my grouchy old man syndrome…

The sentiment was meant to be: "Make `command help` as good as a man page. More people will read that." We didn't mean to suggest to use web pages instead. We also didn't mean not to use man pages at all. We just find more people use the built-in help and web pages, so if you have limited time/resources, it's better spent on those things. In retrospect, perhaps it was worded a bit strongly. I am enjoying the debate,…

Having good `command help` is super important. Agree with the assertion that in-built help is the first and most important.

There have been so many tries to make something better than man pages, and all of them tend to fall down because the solution is usually super complex. Usually, you are dealing with html or some archeo-crontastic typesetting format (which honestly, gets you man + hyperlinks and some better formatting). I guess the dream of GNU info is still alive.

Re: CLI Guidelines – A guide to help you write better command-line programs

#156

Post by kilroy123 » Sat, Dec 05, 2020, 9:06 PM UTC

jen20 wrote: post #40

kitotik wrote: post #16

This is a great resource, thanks for the effort. I strongly disagree with the “ Don’t bother with man pages” advice. It’s extremely annoying when tools don’t provide a manpage. The overhead of opening up a browser to reference command is cumbersome and highly annoying. There are tools such as pandoc that make generating manpages from various source formats very easy. Perhaps it is just my grouchy old man syndrome…

Absolutely - I can't buy into the "don't write man pages" idea. For many years I've had this function in my RC files for macOS: pman() { man -t "$@" | open -f -a Preview; } It opens the given man page in Preview, typeset beautifully. No such thing is available for random text printed to the console, nor is a console pager (as recommended by this article) an acceptable substitute for this.

What a good idea! Thanks for this, added to my aliases.

Re: CLI Guidelines – A guide to help you write better command-line programs

#157

Post by Hnrobert42 » Sat, Dec 05, 2020, 9:12 PM UTC

indymike wrote: post #155

bfirsh wrote: post #152

Earlier quoted context omitted.

The sentiment was meant to be: "Make `command help` as good as a man page. More people will read that." We didn't mean to suggest to use web pages instead. We also didn't mean not to use man pages at all. We just find more people use the built-in help and web pages, so if you have limited time/resources, it's better spent on those things. In retrospect, perhaps it was worded a bit strongly. I am enjoying the debate,…

Having good `command help` is super important. Agree with the assertion that in-built help is the first and most important. There have been so many tries to make something better than man pages, and all of them tend to fall down because the solution is usually super complex. Usually, you are dealing with html or some archeo-crontastic typesetting format (which honestly, gets you man + hyperlinks and some better forma…

I disagree. I never use inbuilt help and only use man pages.

Re: CLI Guidelines – A guide to help you write better command-line programs

#158

Post by Hnrobert42 » Sat, Dec 05, 2020, 9:14 PM UTC

mmalone wrote: post #18

kitotik wrote: post #16

This is a great resource, thanks for the effort. I strongly disagree with the “ Don’t bother with man pages” advice. It’s extremely annoying when tools don’t provide a manpage. The overhead of opening up a browser to reference command is cumbersome and highly annoying. There are tools such as pandoc that make generating manpages from various source formats very easy. Perhaps it is just my grouchy old man syndrome…

They're not saying you shouldn't provide command-line help. Just that you should deliver them through a `help` subcommand and/or through a `--help` flag (like `git` does) because people don't find man pages and because man pages don't work on every platform.

It never even occurs to me to use —help. If a tool doesn’t have a good man page, I just find a different tool.

Re: CLI Guidelines – A guide to help you write better command-line programs

#159

Post by veddox » Sat, Dec 05, 2020, 10:31 PM UTC

chubot wrote: post #84

bfirsh wrote: post #2

Hello HN! We’re Ben, Aanand, Carl, Eva, and Mark, and we made the Command Line Interface Guidelines. Earlier this year, I was working on the Replicate CLI [0]. I had previously worked on Docker so I had a bunch of accumulated knowledge about what makes a good CLI, but I wanted to make Replicate really good, so I looked for some design guides or best practices. Turns out, nothing substantial had been published since t…

Turns out, nothing substantial had been published since the 1980s. The best reference I've found on this is The Art of Unix Programming , which was published in 2003: https://www.amazon.com/UNIX-Programming-Addison-Wesley-Profe... The book is also online for free: Command Line Options: http://www.catb.org/~esr/writings/taoup/html/ch10s05.html User Interface Design Patterns: http://www.catb.org/~esr/writings/taoup/htm…

An excellent book! It was one of the first software development books I read and still shapes my programming style. I probably ought to read it again though, I suspect I would understand a lot of it a lot better now...

Re: CLI Guidelines – A guide to help you write better command-line programs

#160

Post by remexre » Sat, Dec 05, 2020, 10:41 PM UTC

0x445442 wrote: post #81

bfirsh wrote: post #2

Hello HN! We’re Ben, Aanand, Carl, Eva, and Mark, and we made the Command Line Interface Guidelines. Earlier this year, I was working on the Replicate CLI [0]. I had previously worked on Docker so I had a bunch of accumulated knowledge about what makes a good CLI, but I wanted to make Replicate really good, so I looked for some design guides or best practices. Turns out, nothing substantial had been published since t…

It always seems to fall through the cracks in these discussions, maybe because there's not a lot of folks who run the distro, but Gentoo has very nice command line tools.

Do you mean emerge et al? I've been running Gentoo on my main machine for >1 year now, and I'm still having to check the manpage for flags constantly... I guess I wish that it was more explicitly "subcommandy."