History of UNIX Manpages
21 points by cve
21 points by cve
I think the biggest thing most people maybe don’t know about man, is you can create your own sections and make your own man pages. Unfortunately actually doing this is a bit more complicated than it should be, as not every system has a consistent version of man, so you have to read your man’s manpath page(man manpath) and figure out how to do it.
For me it’s editing ~/.manpath on most linux/etc and editing /usr/local/etc/man.d/*.conf on macos.
generally it’s as simple as adding a line like MANPATH /home/zie/man or something like that.
The directory and file structure inside of your own manpath is something like this:
man<section>/<name>.<section>
So if you wanted a command ‘hi’ in section 1 where user commands go:
mkdir -p ~/man/man1
vi ~/man/man1/hi.1
The format is probably mandoc: https://mandoc.bsd.lv/mdoc/ but just plain text works surprisingly well. but again, every system can be a bit different.
Who needs notes and stuff, when you can have your own man pages :)
Good advice!
The contents of man pages will be rendered either by groff or mandoc, which are reasonably compatible with each other. I recommend using the -mdoc macros with their fairly nice semantic markup – there’s no point bothering with the crappy old -man macros, because mandoc can convert -mdoc to -man.
Agreed on defaulting to mandoc for formatting. I was thinking on ancient copies of Unix though, where mandoc definitely isn’t a thing. In terms of man history, mandoc is pretty new(2008 and it took a while to become the default). I seem to remember the BSD’s defaulted to mandoc first, but I could be wrong.
But you don’t really need any markup at all and it all mostly just works. It’s generally “good enough” without any formatting macros, just text.
It’s important to distinguish between mandoc the non-groff man page utilities, and mdoc the markup syntax. mdoc was developed by Cynthia Livingston for 4.4BSD and has been included in groff since the early 1990s, so it’s pretty ubiquitous, and it has been the best choice for writing man pages for decades. The mandoc tools are great for converting mdoc to html or to pre-1990s man macros, as well as being a decent man page viewer.
Good call! I was definitely conflating the two, due to bad memory. Thanks for the clarification!
macOS also dynamically searches for man pages based on $PATH (unless $MANPATH is explicitly set, I think).
just ran manpath -dd and yeah it does. seems to traverse up a directory or two if it detects it is in the bin folder too so there is a hierarchy at play with conventions.