man outputs "geqn should have been given a `-Tutf8' option"
If $PATH has /usr/gnu/bin before /usr/bin, man(1) will spit out a warning, and happily misrender the man-page. Technically, it's a nroff vs groff issue. Regardless, setting $PATH to /usr/bin in main() should do the trick.
Updated by Bryan Cantrill almost 9 years ago
As it turns out, this change broke us -- in the datasets that we use to provision zones, we rely on the fact that nroff will be executed as the nroff in the path (which for us is GNU nroff). We get this to work correctly by running man this way:
alias man='TROFF="groff -T ascii" TCAT="cat" PAGER="less -is" /usr/bin/man -T -mandoc' </pre
That works before this change. With this change, it will execute the wrong nroff (which is to say, the one in /usr/bin) which will die because it can't find the "-mandoc" macro package.
It seems that there are several options here:
1. Back this change out, because it should be resolved by the distro not by the core. (That is, if a distro or user wants to put GNU nroff in the path ahead of the illumos nroff, it's also responsible for delivering an environment that will execute GNU nroff correctly.)
2. Don't set path if TROFF is set. This is the environment variable that indicates which troff to run (not nroff), but if it's set, it probably indicates that the distro or user knows what's going on better than man does -- and man should not be insistent in this case.
(For whatever it's worth, it is not an option for us to replace the "man" alias; it's critical for us that user environment is independent from the platform, and we can't have man working two different ways in two different platform images.)
As an aside, I can't reproduce the original failure when this fix is backed out and GNU nroff is ahead of illumos nroff in the path. When I run on our current GNU nroff (1.20.1) on SmartOS and do not specify "-T -mandoc" I don't get the error (specifying "-T -mandoc" gets a better formatted man page) and when I run on OI (oi_151.1.7) with GNU nroff 1.19.2 and this fix backed out, I don't see the error (quite the contrary, I see a better formatted man page with respect to the terminal).
So: under what conditions was the original bug seen? Can those conditions be reproduced now for any extant illumos distro with the fix backed out? Are there other reasonable options beyond the two I outlined? And if not, which of these two options is preferable?