Which is why the parent advised to treat the man page like a reference document, by searching in it. Some man pages are just badly written and are indigestible even when searching for a specific thing, but in general, that approach works quite often.
And even in the worst case, the man pages give you more context to use in your subsequent web search.
To use the original example, once you've identified that $(...) is Command Substitution, you have something that pulls up meaningful results in every search engine.
Did you have something in mind? I’ve read those man pages before, and I read them again today, and with the possible exception of tags in less (but I’m not sure about that), nothing seems relevant.
If foo has a Texinfo manual (GNU tools like bash usually do) then you can try `info foo` and search the index with i or I for -p. Texinfo manuals also have hyperlinks you can press enter on.
info is a greatly underused system and I'd recommend any *nix users to spend some time learning how to navigate it.
"If you are a bash newbie, you should read the bash manual. If you want proper search for the manual, you should use info. If you want proper use of info, you should use Emacs."
I get that they may be unfamiliar, but learning your system’s tools will pay off over the long run. Search facilities in less and info are generally much more powerful than in your browser.
For bash: 'i' gives me "no indices found" and 'I' says "no index". I can do a '/' search, which finds some "-p" strings, but "n" doesn't work to find the next.
From some other comments, it sounds like "info" uses emacs at its core? So I suppose I'd have to learn some emacs commands, if that's the case.
info works without emacs, but some people prefer emacs' info viewer to the console one. The console viewer does have some idiosyncratic keybindings - for example, "n" means "next node at same level", and "}" means "search for next occurrence". "H" will give you a quick overview.
I'm surprised indexes aren't working for you - unfortunately I don't know of any suggestions to fix that.
as there are a bunch of matches like "...does bar when combined with -p..."
It has been my experience that the definition of switches, unlike their use in examples or other text, occurs as the first thing on the line, so my search expression would be:
/^ *-p
(you likely can't see it, but there is a trailing space, too, to ensure it's just that flag, and not "-parallel" or whatever)
It's possible the text will be tab-indented, in which case:
/^[ ^I]*-p[ ^I]
(most pagers will accept just pressing the tab key in the search string, and it may show up as ^I or the literal tab character)
The caret regex anchor matches at the beginning of line, and the Kleene star matches zero or more of the previous pattern. In English, the above pattern reads “match -p only when it occurs as the first nonblank characters on the line.”
The surrounding context may be different, so adapt your search pattern accordingly.
BSD man pages (and many Linux man pages, though a minority) are written in semantic “mdoc” macros, rather than the classic “man” macros that are strictly presentational.
If you’re using mandoc (http://mandoc.bsd.lv/) as your man(1) program—the default on OpenBSD and a couple of Linuxes like Void and Alpine—it will use these semantics to generate hyperlinks in the terminal using more(1) and less(1)’s ctags support.
So on my machine, your example becomes:
type man foo
type :t
type p
This brings me to the first instance of a command-line flag named “-p” or environment variable named “p” in an itemized list.
It translates to HTML too—check out the links generated by the web viewer, which uses the same backend. https://man.openbsd.org/ls.1
reply