If you don't want to install anything new, you can also write your own man pages with a personal "man section". Just do something like this in your shell:
Then I have files like ~/man/manpj/postgres.pj or ~/man/manpj/ssl.pj. I can say `man pj postgres` to see my own notes. My own collection goes back to 2001 or so. I feel lucky that early on I started putting notes into something so portable. It's one of the few things that has always moved with me to new machines. It is here: https://github.com/pjungwir/manpj/
You don't even need to use proper man formatting if you don't want to. I find that a plain text file comes out pretty well. And when you want to start adding sections/etc, there are only a handful of formatting codes to learn (or copy/paste). I got started from a tiny chapter in O'Reilly's Unix in a Nutshell. You're welcome to steal from my own repo above. (I'm sure the formatting is nowhere close to best practice, but it's good enough for personal use.)
In fact, man pages were made to be extensible in this way. It was assumed that every site installation should have their local manual pages, and every individual user too. It pains me to see so many useless projects like “um” created just because people are assuming that the usual tool for something is restricted to exactly what they are using it for.
> just because people are assuming that the usual tool for something is restricted
To be fair, sometimes it's just because the usual tool is unfriendly. I've just spent 30 mins to extend my manpath as parent suggested (on osx), and it's not working. I have my variables, I have my directories, I have my text files, and still man can't find them. For a tool as old as man, there is precious little debugging information available. It shouldn't be this hard.
Ugh, I'm very sorry to have wasted your time! I mostly work on Linux, but I tried it out on OS X and got the same results as you.
It looks to me like OS X will only search for sections named 1-9 (and maybe "n" too). The MANSECT variable doesn't override this behavior. (I guess it just changes the priority then?)
But you can have a custom suffix after a number. So if you have ~/man/man7/postgres.7pj (note just a 7 for the folder, but 7pj for the file extension), you can open that file by saying `man 7pj postgres`. This is how other programs with a lot of man pages work, e.g. `man 3perl open`. It's not as nice to type a 7 too, but it's the best I can find that works. So I guess on OS X you'd still set MANPATH but can leave MANSECT alone. (You could also probably usurp section 9 or something, and omit your initials entirely.)
Or maybe you could compile a better `man` and put it in ~/bin. :-/
. . . In fact, I find that if I have ~/man/man7/postgres.7pj, I can even type `man xpj postgres` to get my page. Maybe OS X man is just buggy?
Thanks, your help led me to a good solution: Apple man will accept section 0, even though OSX doesn't ship it - so I can squat there. By appending :0 to MANSECT I don't even need the section.
This could be the one time I actually find a good way to note down examples for later reuse. Thanks!
Literally so, if you consider that "ум" in Russian means "mind / intelligence", and "um" is the transliteration of that into Latin alphabet, making it a bilingual pun.
If you don't want to install anything new, you can also write your own man pages with a personal "man section". Just do something like this in your shell:
Here I've added the "pj" section (my initials).Then I have files like ~/man/manpj/postgres.pj or ~/man/manpj/ssl.pj. I can say `man pj postgres` to see my own notes. My own collection goes back to 2001 or so. I feel lucky that early on I started putting notes into something so portable. It's one of the few things that has always moved with me to new machines. It is here: https://github.com/pjungwir/manpj/
You don't even need to use proper man formatting if you don't want to. I find that a plain text file comes out pretty well. And when you want to start adding sections/etc, there are only a handful of formatting codes to learn (or copy/paste). I got started from a tiny chapter in O'Reilly's Unix in a Nutshell. You're welcome to steal from my own repo above. (I'm sure the formatting is nowhere close to best practice, but it's good enough for personal use.)