when do you usually use the man page for a complex command line tool to answer a question you have?
-
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 Depends on the tool. You included --help, which I use more often than man. For git I prefer the internet, because it's too complex and I usually need a combination of options. For others I prefer --help or man. Just today I did that for adduser.
-
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
@b0rk I'm the kind of person who enjoyed reading man pages for leisure.
I read through the entirety of the rsync man page to compose my own favourite rsync invocation once.
The only tools where I resort to web search are shells, because their man pages are really hard to navigate (finding documentation for `read` in the bash man page is ... a nightmare).
Web search is often imprecise and as you note, has gotten so much worse that I am glad I never fully relied on it.
-
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
@b0rk I gave up on groff so long ago that I forgot to try using an LLM to create a man page from HeaderDoc and Markdown. I'll have to give that a shot sometime.
-
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 guess if I am doing stuff on the terminal, the terminal it's the first place I look for help, so --help, man pages, and tldr. My gateway drug to Linux was DJGPP on DOS, and I was using quite a lot the info pages there, even a decade before adopting Emacs. I know Info gets a bad rap, and I admittedly not use it anymore, but I liked that it was giving way more information than a man page, often with tutorial like spirit,
-
@b0rk I have a lingering guilt about not going to man pages first, but often a blog post has been better crafted than the friendly manual. Not all manuals but enough to encourage an antipattern in search first.
I totally agree with your motivation to address/revaluate that.
@RyanParsley to be clear for me i'm mostly interested in figuring out if the man pages can become _better_ so that using them is actually a good experience, not accepting a bad 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 For a complex tool I am almost always looking for an example for a non-trivial use case. The man pages are written backwards for this need.
If I'm looking at a tutorial and want to understand deeply what each flag means, I'll go to the man page for precise answers.
Otherwise I may look at the bottom of the man page for examples. Few man pages have good examples, but they are the useful bits to learn use cases. A focused tutorial: 'tutpage' maybe? Would be better.
-
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 “tldr $command” (if I remember I have it installed) and “$command --help”, then manpage since quite a few “modern” tools don’t come with a manpage
-
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 There's a bunch of reasons for me. I think a big one is I want details, I want things to be explained to me, I want to "build the command" myself : (good) man pages seem to do it more often than online searches ?
Searching online has become more and more infuriating as well, which doesn't help.
Part of it is also "because I'm already here" : if I am already in a terminal, might as well just `man thingy` rather than go to my browser.
It also feels much more information dense if I need to have something in split-screen ? Man pages are often quite compact, and splitting my terminal feels like it adds much less space than having the browser's UI+website spacing+ads (I only recently started using an adblocker, I know...)
But it's a lot of "feels" rather than very thought out, though I definitely do it even for learning a new tool as well. (SSH options and socat are recent examples)
-
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
@b0rk I use them a lot when doing C programming to lookout function prototypes and documentation. When using vim, just place the cursor on the function name, hit SHIFT+K (or 2, SHIFT+K or 3, SHIFT+K to go to specific manpage sections) and you are instantly reading the page, really handy.
-
@b0rk I agree with the sentiment, and I think that's why I installed tldr.sh again recently 🥲 granted that's far less in depth that what is provided by the man pages, but examples are concise.
-
@b0rk using #freebsd and having started on SCO Unix, I’m used to better than average man pages. And I learned sco before the web: so man and Usenet.
—help is my first stop these days.
Knowing how to use man means I can work offline too. So practicing that skill when a fallback is present is a worthy investment
-
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 am hopeful. I will always run -h or --help, and then I will try `man cmd` but ...
I also wrote my GitHub profile as `man wayne`, so...
-
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 for me, it's an old habit. I started in the 90s when these search tools were in their infancy and connections to the Internet were frequently not always on. So relying in man pages and massive books I printed from TLDP were my goto. That still tends to be my preferred starting point.
-
@uastronomer when you say "it's pretty obvious why" what do you mean?
(is it that with stack overflow & the internet generally it feels like there's less pressure to have good docs than when they were the only source of information?)
@b0rk Hmm. Not so obvious after all, now that you've made me think about it.
I mean that dev teams don't always have the resources or interest in supporting what they might see as "legacy" documentation, especially when they are already expected to put documentation on their website, in github, on discord, or wherever else their community hangs out. This wasn't an option in the old days, but now it is.
-
@b0rk same here. I find man pages quite overwhelming, especially for complex tools. Tldr has also become a go to source for me
-
@silvermoon82 @vatine @b0rk where did you find something like that? Seems like a lot of books.
-
@b0rk For a complex tool I am almost always looking for an example for a non-trivial use case. The man pages are written backwards for this need.
If I'm looking at a tutorial and want to understand deeply what each flag means, I'll go to the man page for precise answers.
Otherwise I may look at the bottom of the man page for examples. Few man pages have good examples, but they are the useful bits to learn use cases. A focused tutorial: 'tutpage' maybe? Would be better.
@b0rk search engines no longer surface good tutorials, since they focus on surfacing SEO ad content. LLMs (sadly) do a good job of surfacing the types of "answer looking" options because they are not (yet?) able to be biased towards optimizing to produce SEO ad content revenue clicks.
But LLMs are not authoritative because they only simulate answers. So it is a two or three step process, requiring checking if there is a human source of trust, or confirming with the man page, etc.
-
@djfiander @b0rk and don’t even get me started on GNU texinfo making simple queries suffocate under a gateway drug to RSI viewer (although general props to the depth)
-
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 said I look at man pages first, but I think you edited the question since I wrote that. For git, rsync, and curl, I typically look at the man page first for "small" things, but to some extent that's specific to those programs. Openssl (maybe new since I saw the poll?) I've learned has unhelpful man pages, so I usually search online first for it. -
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 sometimes I get overwhelmed by the wall o’ man page but using slash to search for examples is great. Not all man pages have good example sections though.
