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

[hp@mastodon.tmm.cx]

@b0rk reading the manpage I also accidentally learn stuff I wasn't looking for. Oftentimes I learn that what I was planning to do was the wrong approach and learn how to do it better.

Reading the man page also makes the knowledge "sink in" more for me, so next time I won't have to look it up.

That's why I read the --help and the manpage first. Your brain might work differently, I'm not trying to tell you you should as well.

[witewulf@cyberplace.social]

@gsuberland @b0rk pet hate: when you type <command> -h, and it responds along the lines of “-h is not a recognised option, use -? for help” (or vice versa).

That’s some passive aggressive bullshit, just give me the damn help options 🤨

[cstross@wandering.shop]

@b0rk Assuming the man page docset is properly curated, it should be a comprehensive an authoritative answer to how the tool works.

Caveat: I spent years in a techpubs department writing and maintaining UNIX man pages. I have strong opinions!

[igrok@hachyderm.io]

@b0rk I guess it depends on what you mean by "figure out how to do something"

If I've already figured out what command/function to use but am unsure of the details, man pages are just faster. And if that doesn't help, I'll look elsewhere

If I don't know what man page to even look at, then I'll search first

[zwol@masto.hackers.town]

@b0rk I learned Unix thirty years ago, when the manpages were what was easiest to get at, and so that's what became my habitual first stop ... for things that have manpages anyway. I also have Firefox "custom search keywords" dedicated to the Python and Rust documentation websites.

[fds@mastodon.social]

@b0rk I use the man page reference on the web first. It’s just quicker for me.

[bjb@fosstodon.org]

@phl @b0rk

Yes, sometimes you end up looking at a BSD flavoured man page when you're running Linux and you don't even know there is such a thing as BSD so you don't know to look for a mismatch.

[drahardja@sfba.social]

@b0rk 1. Scan --help. If I can’t figure it out within a minute or two,
2. Web search. If not found,
3. man page

In that order.

[joshrivers@techhub.social]

@b0rk With cross platform differences in CLI tools, the man pages locally are more authoritative than Google.

Mostly, though, I go there first to verify the flags provided in a script or other source, or to convert short flags to long flags in my own scripts, since I prefer that “self-documenting” enhancement.

[eseilt@mastodon.scot]

@b0rk generally with CLI-tools, I already know how they work and just have a new case that I'm fairly confident it can do but need to quickly check the syntax for. In this case, man is the straightforward way to find it.

I have never found them at all useful to learn a new tool, and perfectly useless to discover tools with.

[massa@hachyderm.io]

@drahardja @b0rk I normally go 3 - 1 - 2

[lkanies@hachyderm.io]

@b0rk I do use them pretty often. But it’s usually very hard to find what I want, especially for complex questions. Simpler tools have more useful man pages, more complex tools are basically so comprehensive that every word in the English language is in them so you can’t find anything

[ellie@ellieayla.net]

@b0rk if I'm reading the manpage, it's probably because I'm looking for the exact name/syntax of some rarely-used (usually non-posix) command-line argument or setting and --help elided it.

For trying to learn some larger concept, I find that prose on websites works better.

For trying to figure out what's /really/ supported (eg, an envvar default for some --switch or alternate config file search locations), I'll probably find the git repo and read the argument parser / config loader.

[adrianco@mastodon.social]

@lkanies @b0rk Agree with this.

[illicitonion@hachyderm.io]

@b0rk I think my algorithm is roughly:

If I imagine there's probably a flag that does exactly what I want, or I know there's a flag and I need to remember a detail (e.g. what the flag is called, what the valid options are for it, etc) I'll look in the manpage (and/or --help).

Otherwise I will look elsewhere, and probably never even fall back to the manpage.

[amethyst@toots.n7.gg]

@b0rk I like the convenience and predictable UX of a man page. I can press Esc-H in my shell to open the man page for whatever command I have pending on the command line, and (assuming it has one) I know I can always expect plain text with consistent key bindings to page through it, search for keywords, etc. The biggest unknown is always the potential quality of a man page, but that’s also true for searching online, etc.

[tcb@infosec.exchange]

@b0rk I can use grep to search the man pages and often get what I want much faster than a search engine will give me the same info.

I also find myself leaning even more heavily into man pages as the web becomes AI slop answers that may or may not show real commands and arguments.

[svengeier@mathstodon.xyz]

@b0rk For much of my working life any one computer wasn't guaranteed to be on the internet -- I'm in and out of cleanrooms (and we don't want Russian hacker kids in our $100M hardware so definitely no internet there) and/or in the air trying to make some instrument work on some survey airplane. Now I'm retired but the habit is still to look locally first and only reach outward if that doesn't get me anywhere.

[ppmfloss@mastodon.social]

@b0rk I use GNU Emacs to read manual pages. It has a builtin `man' command to display man pages. It also has hyperlinks to jump to. `man -k' and `appropos' helps for searching. More advanced `info' manuals are there if needed. Offline reading has its own benefits. My main issue is the man pages are very terse at the beginner level. But very smooth once we use a command more than 1 times.

[grumpybozo@toad.social]

@b0rk Man pages have a huge edge over searching the web in that they are generally part of whatever package provides the command they document. They aren’t for an earlier version or a different implementation. They are not usually written by people with weak understanding of the program.