Earlier quoted context omitted.
Still doesn't work for me in Firefox on Windows
Check the shortcut for it and try. Does it work? Weird. I am using a Chrome-based browser though.
I tried it, but that doesn't work either...
CLI Guidelines – A guide to help you write better command-line programs
191–200 of 217 posts
Re: CLI Guidelines – A guide to help you write better command-line programs
#192Hello 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…
Hey, I can't zoom in or out on the website... The font always stays at the same huge size. Using Firefox on Windows
Re: CLI Guidelines – A guide to help you write better command-line programs
#193> If your help text is long, pipe it through a pager.
I disagree that this is a good practice. This prevents me from using my terminal's scrollback to read and/or copy the text. If it comes up in a pager, I either have to re-run the help command every time I want to read it (super annoying when I'm trying to build a command line!) or open yet another window on my screen. And depending on the terminal, this might overwrite a part of the scrollback buffer I had important context in.
If I want to page the help output, I will pipe it to a pager myself.
If the help text is really so unreasonably long that it's unsuitable for --help, hide it behind some other option that --help points me to.
Git does this (effectively treating "-h" the way every other CLI treats "--help", and "--help" as a request to open a man page), and it's incredibly annoying, because no other CLI I use works this way, so it screws up my muscle memory in a way that impacts both my usage of Git and of everything else.
Re: CLI Guidelines – A guide to help you write better command-line programs
#194Earlier quoted context omitted.
Most of what you say is useful common sense, but the bit about not bothering with manpages is plain evil. If anything, the man page must be written before the program interface!
Is there a usage statistic for how often man pages are read? I violently agreed with the article here. There are zero times I wouldn’t rather switch to a browser. Even if I had to dig up my phone from my pocket and search for help there, I’d much rather do that. Also, more and more tools are cross platform and man pages aren’t a thing on windows (are they?).
Really? So if I make a man page for my CLI tool you would assault me physically?
You should take your own description of your beliefs as a red flag to reassess them.
I use a few tools that don’t have man pages and I always find it jarring that I have to leave the CLI to get some basic usage info.
There is already tooling to generate manages and online/html docs from a single source. Reasonable thing seems to be “do both”. I’m not persuaded by “Windows is leaking.”
Re: CLI Guidelines – A guide to help you write better command-line programs
#195Earlier quoted context omitted.
Is there a usage statistic for how often man pages are read? I violently agreed with the article here. There are zero times I wouldn’t rather switch to a browser. Even if I had to dig up my phone from my pocket and search for help there, I’d much rather do that. Also, more and more tools are cross platform and man pages aren’t a thing on windows (are they?).
Really? So if I make a man page for my CLI tool you would assault me physically? You should take your own description of your beliefs as a red flag to reassess them. I use a few tools that don’t have man pages and I always find it jarring that I have to leave the CLI to get some basic usage info. There is already tooling to generate manages and online/html docs from a single source. Reasonable thing seems to be “do b…
> So if I make a man page for my CLI tool you would assault me physically?
What, and ... what?
Re: CLI Guidelines – A guide to help you write better command-line programs
#196Earlier 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…
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."
Re: CLI Guidelines – A guide to help you write better command-line programs
#197Earlier quoted context omitted.
Really? So if I make a man page for my CLI tool you would assault me physically? You should take your own description of your beliefs as a red flag to reassess them. I use a few tools that don’t have man pages and I always find it jarring that I have to leave the CLI to get some basic usage info. There is already tooling to generate manages and online/html docs from a single source. Reasonable thing seems to be “do b…
> So if I make a man page for my CLI tool you would assault me physically? What, and ... what?
I think the previous comment was taking issue with your use of the word "violently."
Re: CLI Guidelines – A guide to help you write better command-line programs
#198Earlier quoted context omitted.
I did not see a personal pet-peeve of mine: If a user of your CLI tool has explicitly requested the built-in help text via --help (or an equivalent switch that requests help) then that help text shall be output on stdout. It always peeves me to do: command --help | less only to find that the explicit request for help (the --help switch) has output the help text on stderr, and I then have to redo the invocation: comma…
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.
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$/;
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.
Re: CLI Guidelines – A guide to help you write better command-line programs
#199Earlier quoted context omitted.
> So if I make a man page for my CLI tool you would assault me physically? What, and ... what?
I think the previous comment was taking issue with your use of the word "violently."
I understood that. I wonder if they googled the expression afterwards so I don’t need to explain it?
Re: CLI Guidelines – A guide to help you write better command-line programs
#200I think one emoji is one emoji too many. Many terminals do not support them. This also addresses the point of terminal independence you brought up elsewhere. The yubi key example looked like using emojis for the sake of using emojis. Several of them were redundant or only slightly relevant (test tube, hand, key).
In all honesty, I just really dislike emojis
The guidelines were all helpful otherwise. It shows that I could only find one nitpick.