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

[qkslvrwolf@mastodon.social]

@b0rk One thing, and I don't know that this is solveable or maybe it was supposed to be solved by info pages but those were hard to memorize how to use, is learning the capabilities of a tool like...up front and at the top.

It's so hard to find the ingredients I need to concoct the correct incantation from man pages, even when I've done the thing with the tool before.

And sometimes you find things that SEEM like what you need but aren't.

[minkiu@mastodon.social]

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

[renedario@raphus.social]

@b0rk i like to look first and then search for examples elsewhere. otherwise my search may not be relevant

[chaos_99@fosstodon.org]

@b0rk I'd say I'd indeed look at the man page first. I've still voted "other", as I immediately turn away if it doesn't give a usage example in the first few lines.
I need to know if it's the right tool for the job, and only very few man pages declare what it does properly. I often need stackoverflow or blogs for that.
Then I return regularly to the man page to look up syntax of what I already know is there.

[ryanparsley@mastodon.social]

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

[rhold@norden.social]

@b0rk i remember this: when i learned about man and started using it, the stuff i wanted to know usually was on page 5 (quick reference / parameters). But i always forget that so it felt frustrating and abandoned them.

Instead I use --help command options. I only go to man when i want to learn the full and long version. But sometimes I do.

[tmcfarlane@toot.community]

@b0rk I generally go to `--help` first, and then a man page, often looking for the EXAMPLE section.

[djfiander@code4lib.social]

@sgharms @b0rk Same here. BSD documentation is usually very good, and complex commands usually have examples that cover the common cases.

Linux man pages, on the other hand, are usually crap.

[sandzwerg@chaos.social]

@b0rk usually I'd first look at --help, then web search, then man page. If I know it's a certain option and I just don't remember the name or how to use it it might be --help, man page then web search.

[kholerik@social.tchncs.de]

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

[jssfr@zombofant.net]

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

[enhancedscurry@mastodon.social]

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

[massimolauria@mathstodon.xyz]

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

@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

[poleguy@mastodon.social]

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

[rudi@hachyderm.io]

@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 :(

[trotfunky@tech.lgbt]

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

[doragasu@mastodon.sdf.org]

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

[ooze@cathode.church]

@b0rk The only reason why I'd use a search engine is to find where the manual is (e.g. what's the URL of the official Podman documentation again?). Top search results are just articles generated from obsolete Stack Overflow answers anyway. Otherwise I hope the man pages and --help give me the basics I need, and point me to more extensive documentation options if needed.

I picked "I'd look there first".

[jeromechoo@masto.ai]

@minkiu @b0rk omg this would’ve saved my mind when I was tinkering with tmux which has the worse man page I’ve ever seen.