Some man pages can be very unwieldy and hard to navigate.

Let's say you were looking for the syntax of the built-in declare command inside of bash(1):

I fire up man bash and just simply search for the string "declare" with the "/" command! Easy peasy!

Welllll, here's the problem:

$ man bash | grep -c declare 34 

You'll need to incrementally slodge through 34 of them using the 'n' key, which here stands for 'nope, nope, nope'.

This is the best optimization I know of:

$ man bash -N turn line numbering on &declare show all the results for "declare", scan them (remember the line number for which one you want) &[enter] turn off the filtered view g(number) go to that line 

There you go. I remember navigating in the 1980s as well.

This is insane. Why is this basic functionality not there?

Why can't I just do something like this:

$ mansnip bash declare 3812 declare [-aAfFgilnrtux] [-p] [name[=value] ...] typeset [-aAfFgilnrtux] [-p] [name[=value] ...] Declare variables and/or give them attributes. If no names are given then display the values of variables. The -p option will display the attributes and values of each name. When -p is used with name arguments, additional options, other than -f and -F, are ignored. When -p is supplied without name arguments, it will display the at‐ tributes and values of all variables having the attributes specified by the additional options. If no other options are supplied with -p, declare will display the at‐ tributes and values of all shell variables. The -f option will restrict the display to shell functions. The -F option inhibits the display of function definitions; only the function name and attributes are printed. If the extdebug shell option is enabled using shopt, the source file name and line number where each name is defined are dis‐ ... $ 

Well, now you can! (ok that was a little obvious)

You even get the line number for further investigation.

Pssttt ... it's also on pypi: pip3 install mansnip-kristopolous

Man pages don't really encode a lot of semantic detail. The format is pretty old. There's been a number of attempted replacements, such as GNU info and BSD mdoc (man 7 mandoc_mdoc) but the ones you use on your system are probably just the traditional boring old man files. Ah, inertia.

Being old, it's primarily concerned with formatting and not any kind of meta-information. And boy can it format! Try using the groffer(1) tool and do something like groffer git-config. You'll hopefully get a very beautiful PDF popping up on your screen, excellent for printing out and keeping in a 3-ring binder next to your Rolodex and FAX machine. Did you know groff is in a lineage that goes back to the 1964 RUNOFF program on MIT's IBM 7094 CTSS? A mere year after Licklider's Intergalactic Computer Network memo leading to what you probably call "the internet" these days.

Anyway, so inside the document source that leads to the pretty man page, there is next to no indication whether something has any special meaning. Let's go back to bash(1) and specifically the source lines for "declare" and "typeset":

.TP \fBdeclare\fP [\fB\-aAfFgilnrtux\fP] [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP] ...] .PD 0 .TP \fBtypeset\fP [\fB\-aAfFgilnrtux\fP] [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP] ...] .PD 

Alright, what do those things mean? You can see that in man 7 man or actually,

$ mansnip 7 man .TP .PD .B .P .I 55 .B Bold 61 .I Italics 97 .P Same as .PP (begin a new paragraph). 124 .TP i Begin paragraph with hanging tag. The tag is given on the next line, but its re‐ sults are like those of the .IP command. 147 .PD d Set inter-paragraph vertical distance to d (if omitted, d=0.4v); does not cause a break. 

Hrmm, well that's a problem. It's effectively just a stylesheet. In fact, the format doesn't look fundamentally different than it did in UNIX v0 in 1970. A mere 2 years after Engelbart demoed a prototype hypertext system, this is well before the semantic web.

"But wait," you say. "If I do man --html bash and then wait for the glacially slow groff HTML post-processor I do indeed get links!"

Yes, the only two semantic concessions given in the modern man format is .SH which is for sections and .TH for the title and ... that's ... it.

"Well let's fix this!" you say!

A third time? lol, ok, have fun. Might work. For now we're stuck with these.

"So there's no surefire easy way to find these snippets then, you can only guess?"

Uh, yep.

Man pages are ridiculously consistent as far as non-semantically structured text goes. This tool usually works fine and if it doesn't, file a bug and go hunting and pecking like you usually do. I'll fix it eventually.

Thanks. enjoy.