Reading Manpages Like a Pro (2018)(blog.yossarian.net)
blog.yossarian.net
Reading Manpages Like a Pro (2018)
https://blog.yossarian.net/2018/01/22/Reading-Manpages-Like-a-Pro
34 comments
[deleted]
These are great suggestions, thank you! I'll add an addendum to the post crediting you for them.
Thanks for the link to ExplainShell; it'll help me a lot as a newbie.
I love that man pages exist, and I get that they predate hypertext, but to me it’s always seemed like a glaring omission that individual man pages don’t link to each other. So much so that for a long while I assumed that they did and that I just hadn’t figured out how to use them.
I wish using man pages felt more like it feels to use Wikipedia.
I wish using man pages felt more like it feels to use Wikipedia.
That's just because you view them in less. I usually view them in emacs, so links work just fine for me.
Hm this looks good too:
https://github.com/lambdalisue/vim-manpager
Any other suggestions? I only looked for a vim plugin since I already use vim, and would rather not add all of emacs just for man, but I wouldn't mind something standalone. Slightly surprised (having only briefly searched 'manpager github') not to find anything though.
Any other suggestions? I only looked for a vim plugin since I already use vim, and would rather not add all of emacs just for man, but I wouldn't mind something standalone. Slightly surprised (having only briefly searched 'manpager github') not to find anything though.
man pages are hypertext, when you find foo(7) it points to the page "foo" from section 7. Whether you can "click" on this link depends largely on what program you are using to view the page.
[deleted]
I find it convenient reading man pages in emacs (doom emacs in my case). The output is colorized, and the pages are linked.
Author here: this is a couple of year old, but I posted it in response to the recent discussion[1] on CLI Guidelines[2]. My main (only?) objection to those guidelines was that they minimized the importance of manual pages.
[1]: https://news.ycombinator.com/item?id=25304257
[2]: https://clig.dev/
[1]: https://news.ycombinator.com/item?id=25304257
[2]: https://clig.dev/
Bat[1] can also colorize man pages quite nicely. The advantage being it will also highlight C code etc.
[1]: https://github.com/sharkdp/bat
[1]: https://github.com/sharkdp/bat
If you haven't heard of it before the 'apropos' command lists all man pages of topics similar to a given text string.
Eg: 'apropos time' will list all man pages that matches 'time'.
Eg: 'apropos time' will list all man pages that matches 'time'.
I have written a simple tool [1] that lets me have my own personal man-like pages.
Whenever I learn something new about a command, I write it in its mann page:
Whenever I learn something new about a command, I write it in its mann page:
mann -e <command> # Opens editor
mann <command>
My #1 problem with man pages is when I want to search for a command flag in a long man page.
If I search for "-f" then I get results for eg, --enable-feces, maybe a bunch of other flags with embedded fs, and a bunch of embedded example commands using those flags before actually getting to the section for -f. I wish there was a special query type that said "this is a flag I'm searching for".
If I search for "-f" then I get results for eg, --enable-feces, maybe a bunch of other flags with embedded fs, and a bunch of embedded example commands using those flags before actually getting to the section for -f. I wish there was a special query type that said "this is a flag I'm searching for".
I agree, this is very frustrating. My “workaround” is to search for ` -f`, that is, two spaces in front of the flag.
Doesn’t always work but _usually_ gets me closer. Hope this helps disabling the feces.
Doesn’t always work but _usually_ gets me closer. Hope this helps disabling the feces.
A solution for this is actually shown in one of the asciicinema examples in the article: prepending \s+ will find only examples with whitespace in front.
https://asciinema.org/a/17Kcnb8PBNIz8JdogOFKVeDQn
https://asciinema.org/a/17Kcnb8PBNIz8JdogOFKVeDQn
I usually get around this by searching for -f<Space> or -f, (sometimes the comma separates a short and long option).
Frankly, I feel like man pages are largely useless and I've given up on them entirely. Instead, I use something like tldr to tell me what I need to do for common use cases, because when I'm trying to solve a certain task, I don't want to learn about 100 different flags for every single shell tool involved. If tldr fails, it's Stack Overflow.
I certainly look to tldr first. But man pages can still be quite useful
Funny how manpages used to be described as "online documentation" and now they are "offline documentation".
Interesting tangential observation, but let's take it offline to an IM or video chat after the meeting.
I find the tips better than the blog post, to be honest. I do like the tips on the blog post as well.
I was wondering: is there a canonical man page on how to read the synopsis? Nowadays, I know how to read it, but I've never found a canonical place that explained it.
I was wondering: is there a canonical man page on how to read the synopsis? Nowadays, I know how to read it, but I've never found a canonical place that explained it.
There is a “colored-man-pages” plugin for zsh, which I had turned on already, and promptly forgotten.
I was puzzled because my man pages are already colorized ;-)
I was puzzled because my man pages are already colorized ;-)
You can also render man pages to pretty typeset postscript and pdf, for example: https://unix.stackexchange.com/questions/444767/export-a-man...
As I recently posted on the "CLI standards" post here, I tend to use this on macOS:
pman() { man -t "$@" | open -f -a Preview; }
There is also apropos which gives you a quick one-liner about a keyword by searching manpage descriptions for it.
Use the -e argument to narrow down the results. For example:
Use the -e argument to narrow down the results. For example:
apropos -e lsAnyone know a good mnemonic for remembering what each section is for?
I find that manpages are often poorly written, e.g. the first lines:
"When you invoke GCC, it normally does..." is painful and should be edited away.
"man is the system's manual pager" you what?
"When you invoke GCC, it normally does..." is painful and should be edited away.
"man is the system's manual pager" you what?
Some manpages are poorly written, some are excellent. Seeking correlation in writing quality in a system where every project submits it's own content by anything other than said authors is flawed.
I'm a big fan of tldr. The outputs are tiny and just show you some common use cases. Much faster and easier than man and a good way to jog your memory or show you a quick overview of what's possible.
https://tldr.sh/
https://tldr.sh/
I upvoted you because I like the idea behind improving the UX of man pages. I have trouble parsing man pages and usually just end up googling for specific use cases.
1. List all man pages of a specific section (e.g. section 4):
`man -k -s 4 . | sort`
2. Output all possible sections:
`man man | head -25`
3. Sometimes there is no man page but GNU info can be used:
`info ed`
`info emacs`
4. A nice website to explain comands and oneliners is explainshell.com. It can also be queried from a terminal quite conveniently.
5. If you're like me, you'll probably often list all the system calls by listing all the pages in section 2. A better way might be to look at the linux source code directly (choose the right architecture):
https://github.com/torvalds/linux/blob/master/arch/x86/entry...