when do you usually use the man page for a complex command line tool to answer a question you have?
-
@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.
-
@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'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 I think it’s muscle memory from having learned Linux/BSD in the mid 90s. Web search wasn’t nearly as effective then, so there wasn’t much choice.
That it has worked well enough and doesn’t require context switching to a browser is probably why I still prefer it today.
-
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
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")
-
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 personally found that doing a complete read of the manpage of a new tool gives me a fairly good idea of what sort of problem the authors wanted to solve, even if I don't recall specific parameters later. Also whenever i run into a weird command somewhere, I look up what all the flags do, both to understand the subtleties and to "prime the cache", so to speak.
Also-also, at least on Debian, a _lot_ of things have manpages, like file formats or some helper scripts. And they have neat references to one another at the end. It's basically a proto-web.
-
@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.
@b0rk The broadening of the programming environment has also taken its toll. The manual covers C and shell programming, but a lot of work today is in different language environments that have their own documentation, some good and some bad. Even in the standard utilities, something like awk or sed is very difficult to learn from the reference manual. Perl at least was always good at making manual pages for every installed package, but they depend on authors to get the information structure down.
-
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 there's also the aspect that man pages are stored on my system when the tool is installed, whereas websites inevitably disappear over time and can be temporarily inaccessible for any number of reasons
-
@b0rk The broadening of the programming environment has also taken its toll. The manual covers C and shell programming, but a lot of work today is in different language environments that have their own documentation, some good and some bad. Even in the standard utilities, something like awk or sed is very difficult to learn from the reference manual. Perl at least was always good at making manual pages for every installed package, but they depend on authors to get the information structure down.
@wollman this all makes a lot of sense to me, personally I've never been a C programmer and so the classic "unix reference manual" style always feels like a bit of an alien life form and like it came from a different time.
-
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 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."
-
@karabaic I've never used openbsd but I'm so curious about the openbsd man page culture because of how people talk about it
do you know if there's anywhere that I can read about the documentation philosophy or about how people relate to it?
@b0rk The FAQ on posting to the openbsd.misc group is a good place to start. after reading man intro. I'd then check the contribution standards on the project.
It's considered incomplete to try to check in code with user-visible functionality that's not explained in the accompanying man page so it can be tested with by reading that page.
