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

[Colin Watson]

Control: reassign -1 perl-modules

[CCing Russ as upstream for podlators.]

On Mon, Dec 12, 2016 at 05:07:29PM +0000, Bjarni Ingi Gislason wrote:
>    * What led up to the situation?
> 
>   A warning was issued.
> 
>    * What exactly did you do (or not do) that was effective (or
>      ineffective)?
> 
>   For example "man perl" with "MAN_KEEP_STDERR=yes"

That is not sufficient; perhaps you have a "man" alias that enables
additional warnings.  I spent a little while in some confusion before
working out that you really meant the following:

  MAN_KEEP_STDERR=yes man --warnings=w perl >/dev/null

>    * What was the outcome of this action?
> 
> <standard input>:57: warning: number register `F' not defined
> 
>    * What outcome did you expect instead?
> 
>   No warning, as the macro "IX" is never used.

Whether the macro "IX" is used is not relevant here.  The comment in the
page source is slightly misplaced; what the segment of code you quote
does is define an empty "IX" request, and *then* fiddle with the "F"
number register.

>   When a manpage is created from a pod file, using the file "Man.pm", the
> register 'F' is referenced in the manpage (perl-modules 5.24):
> 
> [...]
> .\" Avoid warning from groff about undefined register 'F'.
> .de IX
> ..
> .if !\nF .nr F 0
> .if \nF>0 \{\
> .  
> [...]

I can see that that is attempting to avoid a warning.  However, it is
not quite correct.  It should probably be something like this instead:

  .if !r F .nr F 0

I think ".if !\nF .nr F 0" is basically a no-op, even when warnings are
taken into account.  It does arrange that if F was previously
initialised to a negative number then it will be set to 0 instead (since
negative numbers are falsy in groff), but I don't think that matters
much since the subsequent test is "\nF>0" anyway.

>   To avoid a warning from "groff", the argument "-rF=0" must be added to
> every call of "*roff" in "man".

This would not be an even slightly sensible thing to do.  It's not
appropriate to work around bugs in a particular manual page generator by
defining random non-built-in registers for it in advance.  That is, the
"F" register here is not one that is built into groff, or used by man
itself, but rather is one used by the podlators tools for its own
purposes.

This suggestion is akin to requesting that "make" should work around
legitimate warnings about an uninitialised "f" variable in a particular
C program by implicitly defining f to 0 every time it compiles any C
program.

Regards,

-- 
Colin Watson                                       [cjwatson at debian.org]