You often have to read man pages to use Linux/Unix software. However, many man pages are not easy to read. They are very long, not always conveniently arranged, and man does not appear to have any way to handle indices or sections. A great example is man rsync.

I am often in a situation where some popular tool has a LOOONG man page, and I just need to look up the one argument about a specific thing. I don't like having to read the whole thing just for one tiny part of it. It takes a long time, breaks my flow, and if I try to read it start to finish, I am usually very confused and overwhelmed by the time I get to the end. The default pager (I think less) lets me search with /, but it's not very user friendly and it's easy to end up with an too general or too specific search string.

I've been resorting to stuff like man rsync | rg -C 3 symlink, which is much nicer. However, this is still a bit too dumb sometimes. For example, man pacman | rg -C 3 owns does find the switch that tells you what package provides a file, but then you still have to dig through the man page to figure out that it's in the section of switches applicable to -S (which is much higher in the page so ripgrep's context switch doesn't help).

Man pages have been around for half a century. Surely in this time, someone has come out with a way to peruse them that's better than this?

PS: For other people, there are tools like https://tldr.sh/ and https://github.com/cheat/cheat that provide shorter, alternate manual pages. Unfortunately these don't work for my question because they are not comprehensive - they obviously omit many details of the man page, and also there is not always a tldr page for every man page.

posted 9 months ago

CC BY-SA 4.0

9mo ago

matthewsnyder‭

1116 reputation 79 53 179 73