(Possibly relevant to @b0rk 's interests)
So I hit a flag in diff, --unchanged-group-format
. It does not show up in the manpage. It does not show up in --help. You can search both those channels for that string and you will not find it.
You know where it shows up first? If you Google it, you'll get an example in https://www.gnu.org/software/diffutils/manual/html_node/Line-Group-Formats.html.
So why doesn't it show up in the manpage? Well, it does! If you read the entire manpage. With your eyes.
-D, --ifdef=NAME output merged file with '#ifdef NAME' diffs
--GTYPE-group-format=GFMT format GTYPE input groups with GFMT
--line-format=LFMT format all input lines with LFMT
--LTYPE-line-format=LFMT format LTYPE input lines with LFMT
These format options provide fine-grained control over the output
of diff, generalizing -D/--ifdef.
LTYPE is 'old', 'new', or 'unchanged'. GTYPE is LTYPE or 'changed'.
"What do you mean it isn't documented? Of course it's documented. You did read every line and do some template-substitution in your brain, didn't you?"
This isn't advocating for not reading the manpage. If you really want to understand how the tool works, you read the whole manpage. And probably the source code.
... but I don't want to understand how the tool works. I want to diff two files and not have the lines that are the same get emitted.
And I think a lot of application- and solution-generating computer people, most of the time, in most of their careers, are operating on that level of depth. Problems come in too fast and with too much variety. You absolutely go deep on some things. There is no time to go deep on everything.
So how do we address this (other than throw up our hands and say "Relying on Google's fuzzy search of the whole Internet and vibe-coding LLMs is the future actually")? I don't have magic bullets, but a "fuzzy search" mode in something like less
that could take an input like --unchanged-group-format
and twig that it if there's no exact match, it might be related to --GTYPE-group-format
would be nice.
Maybe I should mock that up in emacs. Actually, I bet someone already put it in emacs. ;)