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

[Bjarni Ingi Gislason]

On Mon, Dec 12, 2016 at 06:39:58PM +0000, Colin Watson wrote:
> 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
> 

  Sorry, I forgot the other environmental variables:

MANOPT=--no-hyphenation --warnings=w
MANWIDTH=80

  Removing the standard output is not necessary (people want to read the
standard output!), but with pure "/usr/bin/man", one has to scroll the
screen to see clearly, what it output before the manual page.

> >    * 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
> 

  1) The comment is wrong, because the code was changed from what it
originally was (in my patch in the original bug report; see the last line of
my input in the first e-mail of this thread).

  2) Not all "man" (*roff) programs understand ".if r ..." (or ".g").

> 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

  1) 'F' is not a random register in manual pages.

> "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.
> 

  2) The only place, I find in "podlators" showing the use of 'F', is in the
file "pod2man.PL":

"To get index entries on C<STDERR>, turn on the F register, as in:

    troff -man -rF1 perl.1"

  And "man" is not used to get these index entries, indeed it can't.

3) The solution ("-rF0" or "-rF=0") is totally independent of any bug
(non-understanding) involving this variable.  Does not need any "correction"
to the original code in "Man.pm", which otherwise then most likely needs the
special variable ".g".  Other implementations of "man" might then issue a
warning, which is to be avoided.

> 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.
> 

  The right use of compilers does issue such warnings.  Then the program
should be corrected.

  "make -e" can use environmental variables to change values in the
"Makefile".

  "man" (man-db) does not provide for defining variables on the command line
nor by using environmental variables, and should not need to.

  If maintainers can't see, whether their changes are correct, a (permanent
(future-proof)) solution outside of their domain is called for.

> Regards,
> 
> -- 
> Colin Watson                                       [cjwatson at debian.org]

-- 
Bjarni I. Gislason