when do you usually use the man page for a complex command line tool to answer a question you have?
-
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")
@b0rk I typically start with `-h/--help` flags to see any obvious answer. Then move to man pages after the fact. If I can't find the answer there then move up to a web search.
-
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")
@b0rk I've written man pages before when building internal tools. It was fun learning the ROFF language or whatever. Part of my reluctance to do it with general tools is the requirement to install them as satellite files which is a bit of a pain when it comes to single binary downloads.
I know there's alternate locations you can put them, like
/usr/local/manand even$HOME/.local/share/manthe directory structure after that is also a bit of a pain.
And then there's the need to remember to clean them up after the fact if you no longer use the tool.It'd be neat if some of these apps had the ability to drop the files and a cleanup step to remove them so they could still be single binary. Another thought would be extending man to see if the the requested page is available normally, and if not, see if there's a binary in the path that matches that name? Maybe the man page could be embedded in another section so it didn't have to be executed to generate help?
-
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")I usually first try to figure stuff out myself using man pages and only search online if that takes too long.
-
@b0rk I typically use -h or --help first, then the man page if necessary.
@bortzmeyer @b0rk same. and then web search if the man page is unhelpful. i think part of it is trying to avoid a context switch from the terminal?
-
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")@b0rk personally, it's usually the case that I've used the tool before, I know that it does the thing I want, I just don't remember the invocation details.
So, it's faster to grep the manpage for keywords than launch a web browser.
-
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")
@b0rk I very much agree with your consideration: search is worse & frustrating, look for trustworthy sources. For older people (like me..) it's probably easier or more natural to switch back to reading the manual instead of searching as the first option.
I understand how the doc website was more logical to you. But I think a second reason to prefer a man page or readme or whatever, is that websites are so ethereal. They require maintenance that's often not content related, so they get abandoned. -
I usually first try to figure stuff out myself using man pages and only search online if that takes too long.
Often I learn stuff that I didn't look for.
I might not remember that if and when I need it and look up the man pages again. But I stll like the experience. -
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")@b0rk I want to love man pages. I do find them great as detailed reference material, although sometimes a bit impenetrable.
But I don’t (usually) find they are pedagogically well structured. Eg, in general they do not provide lots of examples of uses, from simple basics to more involved use cases. In general they don’t have split in to “basic use and overview” and “advanced use and detail”.
I might be holding it wrong and / or not very bright, though.
-
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")@b0rk staying in the terminal feels important. Not breaking flow. Checking --help is part of the same task, tabbing out to search is having to start a new task to get the previous one done.
(subjectively, to me, etc.)
-
@b0rk I very much agree with your consideration: search is worse & frustrating, look for trustworthy sources. For older people (like me..) it's probably easier or more natural to switch back to reading the manual instead of searching as the first option.
I understand how the doc website was more logical to you. But I think a second reason to prefer a man page or readme or whatever, is that websites are so ethereal. They require maintenance that's often not content related, so they get abandoned.@ednl yeah, I think the answer to "will there always be a way to get free and reliable static site for open source projects?" is not obvious
When I made that site it felt like github pages would be there forever, and maybe it still will, but I feel less certain of what the future of that looks like than I did.
-
@b0rk I want to love man pages. I do find them great as detailed reference material, although sometimes a bit impenetrable.
But I don’t (usually) find they are pedagogically well structured. Eg, in general they do not provide lots of examples of uses, from simple basics to more involved use cases. In general they don’t have split in to “basic use and overview” and “advanced use and detail”.
I might be holding it wrong and / or not very bright, though.
@benjohn i feel the exact same way if it helps (though I feel more confident that I'm not holding it wrong)
-
@dylannorthrup @b0rk
even more helplessly alone is when I find the single hit obscure comment thread from ‘93 was posted by me 
-
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")@b0rk I think for me, certain tools feel old and unixy, and a man page feels right. And then certain tools feel new and I expect a website.
But also, man pages feel more correct for “what’s the syntax for this specific thing that must have a flag?” and a website or LLM is much more correct for “how do I use this thing in varied ways?”
-
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")
@b0rk one advantage with a man page packaged with the tool is the versioning. The man page should hopefully be the correct version for hte installed tool, avoiding some potential confusion.
I do tend to use man pages for old C libraries if I need docs too. Interestingly I don't do that for Go packages (I either use the local src doc strings that my editor jumps to, or I'll use the pkg.go.dev site).
(obviously there are no man pages for go pkgs, but I rarely use go doc directly) -
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")@b0rk Another reason I can think of is when you're working in environments that have strict version policies, so looking at available man pages gets you the documentation for the version of the tool you have installed. Needing to support older Ansible releases? Gotta check the bundled documentation with
ansible-docbecause the website is the latest rolling version. -
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")@b0rk
Most of all, it's because that's what I have locally on my machinery. If I have that and it's good enough for my level of understanding and purposes, why should I need to go looking on the net?Rubbish man-pages do exist, though, just the same as pretty bad help output. It's when I run into those that I start looking on the net.
-
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")@b0rk I got spoilt by the amazing quality and consistency of OpenBSD's man pages. Even when searching the web, I do 'man <command>' first.
-
@b0rk I think for me, certain tools feel old and unixy, and a man page feels right. And then certain tools feel new and I expect a website.
But also, man pages feel more correct for “what’s the syntax for this specific thing that must have a flag?” and a website or LLM is much more correct for “how do I use this thing in varied ways?”
@hyperpape @b0rk I feel like man pages and --help overlap some in that I use them both as references, but expect man pages to have more explanation than help, and websites to encompass both being a reference as well as having tutorials/deeper explanation?
-
@b0rk I think for me, certain tools feel old and unixy, and a man page feels right. And then certain tools feel new and I expect a website.
But also, man pages feel more correct for “what’s the syntax for this specific thing that must have a flag?” and a website or LLM is much more correct for “how do I use this thing in varied ways?”
@hyperpape I feel the same way but it's also disorienting because I grew up with the Linux coreutils, and they feel old and unixy, but their man pages afaik are unmaintained and I think it really undermined my confidence in man pages as a format even for old unixy-feeling tools
-
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")@b0rk I started out using man pages before the web was a thing and it’s stuck with me. Too often a web search gives you info on a different variant so options don’t work. That’s if you can find details at all, more a now problem than 5-10 years ago. I’ve always been annoyed with the `info` system. It’s been a few years since I last used it. My path is usually try for a man page, then web search, then remember there’s this `info` thing but I usually strike out there too. I do love a good page that has a nice collection of examples, especially for those complicated commands and functions.
