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 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.
-
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 usually am lazy and go through cheatsheets (TLDR, cheat.sh) first to give me a short overview. Usually my usecase is listed
-
@b0rk for me, I think it's a combination of an 'old people' thing and a 'highly suspicious of a lot of the modern Internet' thing.
When I learned to use computers, competent search engines and rich online resources like Stack Exchange were a long way off – even having the Internet in your home without paying per minute wasn't around yet. So you had to develop the skills of finding stuff out from the available local resources like manuals, because that was all you had.
Then good search engines came along, but I was always aware that there's a risk of depending too much on them and losing the ability to figure stuff out yourself. Even now, I sometimes find myself coding without the Internet (or effectively so – laptop on train with terrible connectivity) and it's useful that I can still get things done.
And now search engines are all getting enshittified, and/or monetised, and/or straight-up _worse_ (Google doesn't return the results I actually wanted nearly as often as it used to). And the less said about 2020s answers to this kind of question, the better. So I'm doubly glad I haven't abandoned my old approaches to things. More and more I feel it's important to keep external corporately-provided "do it for you" services at arm's length, and not base your whole workflow on them to the extent that you're a captive market or dependent on them not going down.
@simontatham @b0rk Slightly different area, but for programming I’ve had good experiences with devdocs and devdocs.el as long as the programming language has a large standard library and good docs (doesn’t help with third-party libraries).
-
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 It's complicated. Older tools seem to have better man pages, and modern software puts better information on the web.
I'm sort of sad that info pages didn't take off.
-
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 sometimes look for the man page in Google, because the interface is nicer and/or system doesn't have man installed (Docker containers).
-
@simontatham @b0rk Slightly different area, but for programming I’ve had good experiences with devdocs and devdocs.el as long as the programming language has a large standard library and good docs (doesn’t help with third-party libraries).
@rudi @b0rk yes, programming languages that have a strong culture of good docs are definitely a plus.
Still on the subject of decoupling myself from Internet dependence, I've been working hard on my Rust workflows recently so that I more often use local `cargo doc` or `rustup doc` instead of just going to docs.rs/foo or doc.rust-lang.org/bar. Partly that means I can still consult the docs if the Internet is out of reach, and partly it means I get the version of the docs that matches what I'm actually using.
("Working hard" in the sense that first I had to fix some annoying problems that meant those commands didn't even work for me, like Ubuntu wanted to open the rustdoc output in Abiword, or rustup put its docs somewhere that the apparmor restrictions on snap!Firefox didn't let it read.)
-
@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
@sgharms @b0rk
Agree, but there is a significant gap in the quality between BSDs, Illumos/Solaris and likely other Unixen mans versus Linux ones, especially in a way to provide a useful usage examples for common use cases.In case of a Limux man I may scroll through pages of options to find nothing on how to combine them correctly, thus I switch to a search engine to get what I need (if I don't have time to experiment).
That's why to me Illumos mans are gold, that's why the FreeBSD handbook is _the_ handbook, and so on.
-
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 so much of my "how do I do..." flow is search based now, whether it's web or cmd --help | grep. Less style search in man pages usually means a lot of misses (too many results, or un-fuzzy search missing relevant ones), and navigation is worse than old gamefaqs .txt guides (with their searchable chapter markers)
-
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 the mentioned utilities, mostly man page. ffmpeg? Straight to search.
-
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 use the `tldr` CLI to get the gist of things first and if more is needed, then I dig into the `man` page for the specifics I need.
-
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 In the beginning there was `man pages` and occasionally an O'Reilly manuscript, and it was good.
Then there were blog screeds and sometimes even helpful merchant encyclopediae.
Things went well for a few decades and then a great horde of unbridled machines created great data loss and in-place destruction of blog screeds and merchant storefronts.
This caused much consternation and confusion for the faithful and created a movement to fight back and shackle the unbridled machines.
The old 'tomes of man` persevered and the zealots replicated them and created learning screeds again to spread the word to the masses.
And the reference tomes persevered and were considered the source of truth, even for the old ways that weren't rigid in implementation.
-
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 usually check it first and `/` search in there for keywords related to what I want to do, then if I don't see anything useful, I switch to duckduckgo.
Basically, I am already in the terminal, and there's a chance that I could find my answer in 5-15 seconds, so I try, and then move on if not.
Now, when I have successfully done that for a command before, the next time I have an issue with that command I will waste 15 minutes in the manpage because it was so easy the last time and I shouldn't give up.
-
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 The Unix User's/Programmer's Manual is the *reference* documentation, but was never intended to provide introductory guides or conceptual overviews — as originally distributed those were separate documents. The man page should tell you how to do the thing when you already know what you want and that there's a command/function to do it, and you just need the invocation details. Unfortunately the higher level conceptual documentation has fallen by the wayside.
