when do you usually use the man page for a complex command line tool to answer a question you have?

[spills@hachyderm.io]

I always go to --help first to get an idea of what my options are or to scope my question better, then I can search for examples using whatever option vs searching "how to X" if that makes sense

[b0rk@social.jvns.ca]

@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

[b0rk@social.jvns.ca]

@aburka that's what fish does! Well it just opens the HTML file in the browser, no need to start a local web server for those docs

[wollman@mastodon.social]

@b0rk tcl, as I recall, shipped with a whole new "section" of manual pages for its intrinsics that you could opt to install, but I don't know anyone who actually wanted that. That was in the days when any system worth its salt shipped with at least nroff and -man macros — some systems made that a separately licensed add-on, forcing third-party software distributors to ship preformatted documentation. That was probably the start of the downfall, because it opened up the options for doc authoring.

[culper@infosec.exchange]

@b0rk I think most man pages have a lot of detail and are great resources. But.....While they go into great detail they lack the concept of basic use. Take the tar command. Great compression utility with lots of options. Most people just want to decompress files. How do you do that? I had to search on google for the answer. Yes the proper syntax was buried in the man page in different parts. I think a basic command example at the begining of the man page about what most will be using the utility for would help.

[mutecipher@mastodon.social]

@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.

[gibwar@infosec.exchange]

@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/man and even $HOME/.local/share/man the 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? 🤔

[dave@rascalking.com]

@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?

[sagefault@infosec.exchange]

@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.

[ednl@mastodon.social]

@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.

[benjohn@todon.nl]

@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.

[seachdamh@101010.pl]

@b0rk There are still cases where a system has no internet access (regardless of whether for technical, organizational, or legal reasons). Every tool should have reasonably comprehensive offline help/documentation; it could be --help (if it's complete), it could be man, it could be info, or even documentation in plain .txt — it doesn't matter, as long as I still have access to the documentation on a system cut off from the network.

Every non-trivial tool failing to do this is just deficient.

Additionally, websites (contrary to popular belief) aren't eternal. They disappear—and the more niche the tool, the more likely it is to happen. And when they go, the documentation vanishes with them.

[swift@merveilles.town]

@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@social.jvns.ca]

@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@social.jvns.ca]

@benjohn i feel the exact same way if it helps (though I feel more confident that I'm not holding it wrong)

[benjohn@todon.nl]

@dylannorthrup @b0rk :-) even more helplessly alone is when I find the single hit obscure comment thread from ‘93 was posted by me 😭

[hyperpape@hachyderm.io]

@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?”

[nettles@mastodon.scot]

@b0rk Very much depends. If I think it's likely solved by a simple feature of the tool, like a subcommand or option then I'll look in the help or man page. If it's a higher order "I want to solve this uncommon/situational problem" I'll probably go for a web search... and then cry to myself that the search engines are so bad.

[tmcfarlane@toot.community]

@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)

[gibwar@infosec.exchange]

@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-doc because the website is the latest rolling version.