Bug#847972: man: Eliminate warnings from '*roff' about the undefined register 'F'

[Colin Watson]

On Tue, Dec 13, 2016 at 11:17:18PM +0000, Bjarni Ingi Gislason wrote:
> On Mon, Dec 12, 2016 at 06:40:21PM -0800, Russ Allbery wrote:
> > Apologies for the regression; this is the confluence of two things that
> > basically no one ever does (enable nroff warnings, and use this obscure
> > indexing code), so it's essentially never tested.
> > 
> > >   1) 'F' is not a random register in manual pages.
> > 
> > It is, though.  It's a completely random register picked by Tom
> > Christiansen years and years ago to hang this feature off of because it
> > wasn't used for anything else.  From the nroff and man-db perspective,
> > it's just some random user-defined register, not anything special.
> 
>   I have a different conception of "random".  The variable 'F' is in all
> manual pages, that "pod2man" creates.

It is "random" from man-db's point of view, because it has no standard
or predictable meaning across the set of all manual pages.

pod2man is just one way to create input files for nroff, and man-db pays
it no special consideration beyond just generally making sure that it
can parse its output properly.  Some other manual page or manual page
generator might quite legitimately define the 'F' number register to do
something completely different.  (It would not surprise me to find some
page deciding to use it for something to do with input file names, like
\n[.F], or fonts, like \n[.f], for instance.)  man has no business
predefining 'F' by default simply in order to work around a pod2man bug;
doing so might well cause problems elsewhere.

Even if this predefinition didn't happen to cause any problems today,
it's completely the wrong layer for the fix, and would be terrible
software engineering.  Fix problems at the layer where they arise; don't
patch around them elsewhere.  That way lies spaghetti architecture.

> Besides that, it is an "input variable"(!) for "*roff".

I'm not sure what your exclamation mark signifies or why you believe
this makes a difference.  pod2man may have set things up so that you're
expected to predefine that variable in order to enable this indexing
thing, but that doesn't mean it should be given any special
consideration by man-db.  Again, it's simply the wrong layer.

>   So there are only two small changes needed to "man.c":
> 
> 1) The default value of "roff_opt" is "-rF0" and not an empty value.  Plus a
> comment about the reason.
> 
> 2) Adding an explanation to the manual, saying what the default value is and
> why.

You can absolutely set this environment variable locally as a workaround
to make the (off by default anyway!) warnings go away; this kind of
thing is why that variable exists, and I'm glad you find it useful.
However, for the reasons given above I won't change man-db in the way
you propose.  The fix belongs in pod2man.

Regards,

-- 
Colin Watson                                       [cjwatson at debian.org]