Man pages are specifically reference documents, not tutorials or guidebooks. To say one should use a man page is to say that one must completely digest the entirety of the tool prior to ever actually using it. That’s just simply not feasible, nor should it be expected of anyone beyond trivial tools. Man pages simply don’t provide the context for solving a problem like a guidebook or tutorial would, which is why there are so many sites that start with a problem and then explain the tools.

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.

Is there some trick to searching man pages that I don’t know? Because my usual experience is:

  type man foo
  type /-p
  type n n n n n n n n n

as there are a bunch of matches like “...does bar when combined with -p...”

A presentation of man pages that used hypertext would make me a lot happier.

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

That’s awesome! I think a table of contents could be nice addition for the HTML version (at least for pages that are longer than less).

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.

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.

Thank you for the comment! I've always been aware of the info pages, but it's honestly been years since I've tried to use them.

This thread is a good reminder to give it another go.

Thanks. Is there a good way to open that in a browser, rather than a console?

In addition to the HTML info pages hosted by GNU[1], a variety of GUI texinfo readers are available, such as tkinfo[2].

[1] https://www.gnu.org/software/bash/manual/html_node/index.htm...

[2] http://math-www.uni-paderborn.de/~axel/tkinfo/

I don't know if you can locally, but they're often published online in HTML format, like at https://www.gnu.org/software/bash/manual/html_node/index.htm....

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.

In general, the best way to read Info documentation is inside Emacs.

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

Kind of a deep rabbit hole, isn't it?

Not in this case; the bash manual is not in Info form, but a regular old-style Unix man page.

You might want to search with

    /   -p

Thanks, but I think this validates a demand for real hypertext.

While you’re waiting for the rest of the world to agree with you and then implement the true hypertext manuals, consider sharpening your regex saw.

In OpenBSD, we have true hypertext manuals today: https://news.ycombinator.com/item?id=16089300

You can use apropos to search names and descriptions inside man pages. For example:

    $ apropos timezone
    Date::Manip::DM5abbrevs (3pm) - A list of all timezone abbreviations
    dm_zdump (1p)        - timezone dumper
    Time::Zone (3pm)     - - miscellaneous timezone manipulations routines
    timezone (3)         - initialize time conversion information
    tzfile (5)           - timezone information
    tzselect (1)         - view timezones
    tzselect (8)         - select a timezone
    zdump (8)            - timezone dumper
    zic (8)              - timezone compiler

Can even search using regular expressions.

    man man
    man less

Not a joke. Learn the simple tools that help you daily.

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.

I'm sorry for sounding condescending! I did not understand your problem initially.

What helps me somehow is the fact that definitions in man pages are usually start on a new line and are indented by several spaces.

    man bash 
    / -o

This finds an inline mention, not very useful.

    man bash
    /^ +-o

This finds the definition: start of line, then some space, then the -o.

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)

Usually options are typeset similar to

    -p

    Potrzebie mode ...

So search for it, e.g.,

    /^ *-p

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.

You can also do keyword searches across all man pages like:

    man -k <keyword>

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.

I generally find things easier to learn with reference documents than tutorials unless I'm unfamiliar with the problem domain and have no mental model to map things to. That's very rare these days, so reference documents are the way to go.

Amusingly, reference documents are themselves increasingly rare, and what you usually get is a rough tutorial and set of examples that cover perhaps 15% of the feature set, and need to dive into the source to figure everything else out.

Look up the name of the concept in the manual and search for that. Compare Google or Stack Overflow searches for <() versus “process substitution.”

It is a reference, and searching for the pattern GP mentioned finds you references to arithmetic expression evaluation and to command substitution. Those are the terms one can Google for if further explanation is required.