This was essentially my primary motivation for writing `cheat`. The `man` pages are thorough, but often lack examples demonstrating the common use-cases.
I eventually tired of Googling "how to extract a tarball" (because I'm too lazy to read the lengthy manpage), and decided to create some supplemental tooling.
The feeling that a single actual example would make the whole thing a million times clearer.
Sometimes there's also an `info` file with more detail.
And one of my pet peeves. Do a search "How to briwyw the gomleqq" and the first one you look at has screen after screen of how to install Linux and everything and then finally at the very bottom it is finally revealed
gomleqq --briwyw 40 --eiei-dddd 9
and that's the little bit of knowledge that I needed all along, along with that fact that 40 needs to be at least 4 times bigger than 9 or you'll get dropped packets.
going back and forth from a search tab, the results, and this comment, I'm over here trying to remember FAST in case Im having a stroke or what. Is this tool written in Klingon or something?
The extensivisity is part of the problem - you don't want paragraphs upon paragraphs, you often just want a short reminder as to which option is which.
But so many programs have decent built in "help" now it's not as big a deal - I remember when ls --help would just return every possible valid option on one big line ... which now Google does for us: https://www.google.com/search?q=ls+options
My impression is that people stopped filling their man pages because the information got into info pages when there was an ongoing campaign to create those (because the format was much more expressible).
And then, the users simply didn't learn how to use info, so developers dropped those and kept only the very short man pages.
The Info command kind of sucks to use though. It's way more complex than you would expect for a manual viewer. The help screen itself is 300 lines long and full of stuff like:
LFD (select-reference-this-line) Select reference or menu item appearing on this line
The help page talks a ton about xrefs and nodes and references and echo areas and tree searches without ever explaining what any of those things are. The h key as always does nothing.
Info pages are like big old clunky manuals with diagrams and schematics and "theory of operation" chapters. Great when you're on the ground doing maintenance.
Man pages are like quick reference handbooks. Great when you're already at 30,000' and just need to keep the plane flying.
That kinda makes me think if it would be possible to write a tool that patches these cheat sheets into man pages that don't yet have an EXAMPLES section.
I eventually tired of Googling "how to extract a tarball" (because I'm too lazy to read the lengthy manpage), and decided to create some supplemental tooling.