Customising man(1) for more readable manual pages
By Tim Cook on Nov 08, 2005
This entry can be considered a test run, or it can be considered as an entry that will stop my next entry from being the first and only entry when it is released. These things are true, but I hope this entry will be of interest anyway.
I am still a habitual user of the "man" command in Solaris (and other Unixes). It has pretty good response time, and the format is familiar. I did notice a number of years ago that the format could be better. All sorts of terminals are able to display bold and underlined text, and printed man pages show some elements as bold, but man(1) on Solaris only shows underlined elements (see below).
My interest was piqued when I re-acquainted myself with Linux, and noticed that man(1) was showing bold elements. I had to investigate.
I did a few things like "truss -f" on the man program, "strings" on the binary, until I discovered that Solaris' man(1) was different in that it was using a "-u0" option to nroff(1) when formatting the text. This flag was undocumented at the time, but I discovered that if I hand-built a man page and used "-u1" instead, I got bold text.
I was obviously not firing on all cylinders that day, as I chose to customise man(1) by putting a copy of /usr/bin/man (the binary) in my ~/bin directory, then editing the binary, changing any occurence of "-u0" to "-u1".
When I next upgraded my workstation, I then had to replace the binary with a script that called a release-specific binary, as I was then using multiple releases of Solaris on different systems.
Eventually, the injector on cylinder 3 cleared, and I figured out how to do it with a script that effectively interposed on /usr/bin/man and /usr/bin/nroff. This would also work on many releases of Solaris (currently working fine on S10 and the most recent build of OpenSolaris). At the same time, I figured I could use a custom PAGER program for displaying man pages, and implement this in the same script.
If you feel envious and want this for yourself, download the script from here. Put this in a directory in your PATH that comes before /usr/bin and /bin, then link it to "nroff" in the same directory (e.g. "ln ~/bin/man ~/bin/nroff"). You will then get what I see: