Julia EvansFeb 20

when do you usually use the man page for a complex command line tool to answer a question you have? (like git, openssl, rsync, curl, etc)

(edit: no need to say "i use --help then man")

I’d look there first
57.6%
Only after trying other options first
33.2%
Never
6.4%
Other / not sure
2.8%
Poll ended at .
Show threadJulia EvansFeb 20

i'm very curious about everyone who says "I'd look there first", if I want to figure out how to do something new I think I'll usually google how to do it rather than look at the man page, and then maybe later look at the man page to look up the details

(I've gotten enough of these answers:
- "I like that man pages don't require changing context"
- "with the man page I know I have the right version of the docs")

Show threadJulia EvansFeb 20
i think part of the reason I'm feeling interested in man pages right now even though I rarely use them is that search has gotten so much worse, it's frustrating, and it makes it feel more appealing to have trustworthy sources with clear explanations
Show threadJulia EvansFeb 20

also it just occurred to me that the one time I wrote a command line tool (https://rbspy.github.io/) I didn't write a man page for it, I made a documentation website instead. I don't remember even considering writing a man page, probably because I rarely use man pages

(not looking to argue about whether command line tools "should" have man pages or not, just reflecting about how maybe I personally would prefer a good docs website over a man page. Also please no "webpages require internet")

Introduction - rbspy: A Sampling CPU Profiler for Ruby

Show threadJonathan Hartley
@b0rk I suppose that adding a man page requires extra hurdles of not just creating the man page itself, but packaging your tool such that the man page gets installed along with it. Now you have to make a .deb and and .apt and whatever else, instead of just saying "download this script or executable and run it."
Feb 20 at 3:13pmWeb
Show threadJulia EvansFeb 20
@tartley yea I'm not sure if anyone's ever packaged rbspy for Debian because (at least at the time) packaging Rust projects for Debian was hard or maybe impossible
Show threadTony FinchFeb 20

@tartley @b0rk an idea i copied from git is to make -h print the short summary and --help brings up the man page

i have embedded the man page in the script or binary so it doesn’t have to be installed separately (tho it only works with the man command if the man page is installed)

Show threaddgelessusFeb 20

@fanf @tartley @b0rk TIL that Git's -h and --help do different things. What an unfortunate UI though :( It goes completely against the principle of long options and the established behavior of -h/--help in every other CLI tool, and even the git(1) man page claims that -h and --help are identical??

Very useful to know though. Previously, I used tricks like "git remote blarg" to get the short help, and was a little confused/surprised that there was no better way to see the short help text.

Show threaddgelessusFeb 20

@fanf @tartley @b0rk Oh, it's actually even worse! `git remote -h` shows the short help, but `git -h remote` outputs the man page.

`git remote --help`, `git --help remote`, and `git help remote` also all show the man page. So the specific spelling `git <command> -h` seems to be a special case. This is extremely unhelpful behavior for an option that's meant to be used when you don't know how to use a program... :(