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

[bew@floss.social]

@b0rk it depends on the question..

- For "can I even do X..." (or if I know it's quite annoying to get the params right), I like to ask Perplexity
- For "I know I can do X, what's the param again", I like to use `--help` or `man`
- For "I don't remember the exact semantic of X, what does it do exactly?", I like to use `man`

[davecb@hachyderm.io]

@b0rk One of the best features of the older man pages was a keyword-in-context index. See https://en.wikipedia.org/wiki/Key_Word_in_Context for an example.

If I thought of a word, I could see where it was used in man pages, and ONLY in man pages. Low noise, high granularity.

I'm tempted to make one as Appendix B of a small reference book I'm writing. I bet I can use my concordance file and grep for each of the words, reporting chapter instead of page in on-line formats.

[duien@xoxo.zone]

@b0rk I struggled with which option to choose for that exact reason! There’s a fairly complex interaction between what kind of new thing I’m doing, how the command is structured, and how much of an idea I have of how to approach it. A “what flags do I need to pass” question (more common with curl) will almost always start with man, but for “how do I even approach this” (more common with git) I’m more likely to start with search. But if I think I can find the right man page, I start there.

[aartaka@merveilles.town]

@b0rk two points:

• Investing in collateral knowledge of other options and the information the developer / documenter put there on purpose. The implied idea is that they know what to emphasize in docs.

• Preference for local information. So it’s --help/man > Google/SO > everything else *gestures vaguely*

[phl@mastodon.social]

@b0rk The point of having a man page (or as you edited the original post: a --help) is that it's self-contained and, hopefully, true to the actual thing you're trying to run. The website requires an internet connection and it might be about a newer version than you have (did your distro or you forget to upgrade the tool?) or older (did the author forget to update the documentation?) and while a site is often a better UX (graphical browsers and whatnot), those are issues to be considered.

[cate@mastodon.xyz]

@b0rk note: Because Debian requires man pages, I notice that lot of the are written by debian developers, so I assume also a lot of developers don’t use man pages. (note also that writing man pages was very difficult, not just content, but technically: complex non standardized language, various tools, and I still not sure there is a guide on conventions)

[colen@hachyderm.io]

@b0rk same, I would only look at a man page in direst need, they are borderline unusable to me from the perspective of “someone who doesn’t know the command at all”

[kalfeher@infosec.exchange]

@b0rk --help and man let me figure things out without changing context. sure I have a browser right there, but while on the cli, I want my answers there.

Red Hat drew the same conclusion with the use cases for their wonky Lightspeed cli LLM helper thingy.

ofc if theres no man page Ill go to the website and not really think about it.

[fanf@mendeddrum.org]

@b0rk if i’m answering a question about a tool that i’ve used before, then i’ll check the man page

if it’s a new tool or a new problem and i don’t know the lay of the land, i’ll probably read blog posts about how others have tackled it to gain confidence that i’m looking at a suitable tool, before digging into its documentation

[teivel@mas.to]

@b0rk I'm kinda half and half right now between `man` and `cmd --help`, I've been using `man` more since I have `nvim` set as my `man pager`, so I can easily grep for parts of the documentation. For example, today I was looking at a series of commands `git clone && git checkout $tag && git submodule`, and I thought to myself, that looks redundant, bet you can do all that with just `git clone`, so I grepped the git clone man page for `checkout` and `submodule` to find all the relevant flags

[jasonkarns@indieweb.social]

@b0rk one thing that I don’t think gets enough attention:

If I go on the web I have to worry about versioning. Is my version too old? This doc might not apply to me. Or maybe the online post is too old and my version has newer/better options or features. Man page and -help are locked to my actual version.

[bracken@ruby.social]

@b0rk I almost always do a man page (habit) or especially --help first. Though, unless I'm already kinda familiar and am just looking up a specific flag I usually also exit it right away because I find most quite confusing unless they already have an example usage that fits my exact case.
Then I do a web search for my specific need and usually find it easier there.

[fanf@mendeddrum.org]

@tartley @b0rk an idea i copied from git is to make -h print the short summary and --help brings up the man page

i have embedded the man page in the script or binary so it doesn’t have to be installed separately (tho it only works with the man command if the man page is installed)

[toasted_flakes@mastodon.social]

@b0rk Google used to show me what I needed quite quickly. The search quality feels like it declined, and I now know those tools enough I’ll look up the man page first.

[ferrix@mastodon.online]

@b0rk what side of the line is "I search the web for the man page because the browser is the best view/search/scroll experience but the data is in man page"

[knees@mathstodon.xyz]

@b0rk 100% agree with this. I sometimes joke that this is how you know search is so bad these days, that people actually have to use man pages now

[ferrix@mastodon.online]

@b0rk oh god I hadn't thought about hallucinated manual web pages