Finding just the snippets in man page you care about
Project description
The Problem
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?
Introducting Mansnip!
Why can't I just do something like this:
$ man bash | mansnip declare
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)
Why hasn't this existed forever?
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,
$ man 7 man | mansnip .TP .PD .B .P .I
.B Bold
.I Italics
.P Same as .PP (begin a new paragraph).
.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.
.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.
It's not that terrible though!
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.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for mansnip_kristopolous-0.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 964464a23ea7260d873c446e91b0bd0ba94d86487a7b873d5ccfc83f248f2b54 |
|
MD5 | 961223dcded079f5d27b62b2b25dcf83 |
|
BLAKE2b-256 | 8d629e6a7b18f45ea9bc22a14ac4d55f30e5d5b6ae43d325ddafd61fb619aeb6 |