Yes. Please ditch the man pages and instead get out of the terminal and get tracked in the browser. Like this website which needs Google ad tracking.
CLI Guidelines – A guide to help you write better command-line programs
91–100 of 217 posts
Re: CLI Guidelines – A guide to help you write better command-line programs
#92This 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…
> "Don’t bother with man pages."
I also consider this terrible advice. 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` )
Re: CLI Guidelines – A guide to help you write better command-line programs
#93Quit and help are the two most important and basic command that should have priority. The rest you can learn. These two is hard. Exit, quit, crt-d, crt-z... and help is even higher especially if you give an error response.
Re: CLI Guidelines – A guide to help you write better command-line programs
#94Could you make the site usable without javascript? Right now there's a sidebar with a transparency that overlaps half of the paragraphs.
Re: CLI Guidelines – A guide to help you write better command-line programs
#95This is a great resource. I will return to read it closely next time I am designing a CLI.
One thing that puzzled me: `git push` is given as an example of the principle "If you change state, tell the user". Its output is:
$ git push
Enumerating objects: 18, done.
Counting objects: 100% (18/18), done.
Delta compression using up to 8 threads
Compressing objects: 100% (10/10), done.
Writing objects: 100% (10/10), 2.09 KiB | 2.09 MiB/s, done.
Total 10 (delta 8), reused 0 (delta 0), pack-reused 0
remote: Resolving deltas: 100% (8/8), completed with 8 local objects.
To github.com:replicate/replicate.git
+ 6c22c90...a2a5217 bfirsh/fix-delete -> bfirsh/fix-delete
$ git push
Writing objects: 100% (10/10), 2.09 KiB | 2.09 MiB/s, done.
Pushed 10 objects to github.com:replicate/replicate.git
+ 6c22c90...a2a5217 bfirsh/fix-delete -> bfirsh/fix-deleteRe: CLI Guidelines – A guide to help you write better command-line programs
#96This 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…
I think distros should disallow binaries that do not have man pages. I remember on SunOS 4.x, for example, pretty much everything in /bin and /usr/bin had man pages. You wonder what something does? Read the man page. If you produce a binary and fail to produce an accompanying man page, you have committed a crime against humanity.
Re: CLI Guidelines – A guide to help you write better command-line programs
#97My advice as a user of CLI: - no emojis please, ever - if you want to make it look nice, use ANSI escape codes for color rather than emojis. even then, don't use color alone to convey meaning because it will most likely get destroyed by whatever you're piping it to. - please take the time to write detailed man pages, not just a "--help" screen - implement "did you mean?" for typos (git style) and potentially dangerou…
git’s behavior is really nice: any program on $PATH named `git-foo` can be accessed as a sub command `git foo`. I’ve personally taken this a step further, and wrapped git in a shell function so that `git cd bar` navigates to the directory `bar` relative to the repository root.
Re: CLI Guidelines – A guide to help you write better command-line programs
#98Earlier quoted context omitted.
I agree, if you press Ctrl-C vim (with default settings) literally tells you how to quit. `\n~` in SSH is completely unrecoverable.
If you are already using SSH in a situation where ‘exit’ doesn’t work, it becomes more reasonable to assume the user will know.
I don't understand what you're saying here; could you expand a bit?
Re: CLI Guidelines – A guide to help you write better command-line programs
#99This 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 is Preview?
Re: CLI Guidelines – A guide to help you write better command-line programs
#100What is the current best practice for making machine readable documentation of methods and options available in a CLI program? Similar to how OpenAPI works for RESTful services.