Post History
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 ...
Question
man-page
#2: Post edited
by
matthewsnyder
·
2023-08-21T18:30:56Z (9 months ago)
- 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?
- 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.
#1: Initial revision
by
matthewsnyder
·
2023-08-21T18:27:33Z (9 months ago)
Ergonomic way to search man pages
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?