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

[Bjarni Ingi Gislason]

On Wed, Dec 14, 2016 at 12:09:37AM +0000, Colin Watson wrote:
> 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.
> 

  It is just undocumented.  "pod2man" uses it for input; its meaning is just
documented there.  By documenting it better there, and in the manual pages
of all implementations of "man", problems are avoided.  A warning about it
being undefined avoids future trouble and time theft, when the cause of the
warning is fixed.

  It has a definite meaning in pages made by "pod2man".  It is not used in
other manual pages as an input register, if it would, it would then be a bug
in them, and nowhere else.  Call it a reserved name (by custom or tradition)
for an input register to manual pages.  I have not found an use of a numeric
register 'F' in manual pages, except in those created by "Pod::Man".


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

  "man has no business ..." is your belief, which is wrong.  It is
responsible for providing the commands it uses with the correct input,
correct parameter.

  Where is this bug in "pod2man" (manual page) and what exactly is it, and
why?

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

  The problem arises inside "groff", it issues a diagnostic, not the code in
the manual page.  Proof it otherwise.

  Possible later problems are then caused by the wrong or premature use of
this name 'F' in other places.

  The problem arises (has its beginning) inside "man" when it runs "groff".
So it arises in that layer, not later, although it is only reported later in
the row (pipe).  Otherwise it could not be fixed there (in the "man" or in
its defined environment).  Proof it otherwise.

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

  A value of an input variable is in the environment of a command, not
inside it.

  "man" gives "MANROFFOPT" a special consideration, thus everything in it,
for example "-rF0".

  Why is it the wrong layer?

  If true, a change in that layer can't make the diagnostic from "groff" go
away, make it unnecessary.  But is does, by a least three methods, all in the
"man"-layer (or "man-db"-layer), outside of "groff" and the manual page.

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

  Why just locally (for one user)?

  Why a workaround?

  A workaround caused by what bug?

  A workaround usually means, that the error is somewhere else, and is not
yet fixed!

  My ideas are neither final nor absolute.  I have found a better place
(still in the "man-db" package) than an environmental variable.

  I repeat: What is the bug in "pod2man" (manual page) and why?

  "groff" still emits the warning, independently of what is done to it
afterwards!

  What you suggest is to silence a criticism!

  Only one example is needed to disproof your claim, no number of your
examples can proof your claim.

  1) A "troff" aborts the processing when it encounters an undefined
register (used as an input register).  Where is the bug now and why?

  2) The manual page checks if an input register is defined, if not it
aborts with a diagnostic message.  Where is the logical error now and why?

  3) Case: 'F' is not predefined in "man".  Manual pages produced by
"pod2man" use that input register since (year).  One writer or more make
manual pages that uses 'F' as an input register with different meaning from
each other.  How do these manual pages coexist without trouble on the same
installation?

How is this conflict solved?

  4) The code in a manual page or pages, that use an input register, defines
the values 1 and 2 as valid, other as invalid.  Where is the bug and why,
when the code in it aborts because the input register automatically gets the
value 0?

  I withdraw my patch, as it only hides a symptom, and I do not want that
any more, as I know the cause of this symptom and how to cure the cause.

###

  I know of two potential bugs in "pod2man":

1) Documentation: An documentation about the input register 'F' is missing.
Input data should always be explained and declared as such.

  Add an explanation of a diagnostic message about the undefined register
'F', and how to fix it at or near the root of the cause.  That can depend on
the implementation of "man".

2) Code: "\s0" is used in the definition of the string "C+".  That does not
work, if the string gets resized.

###

"This second radical novelty shares the usual fate of all
radical novelties: it is denied, because its truth would be
too discomforting.
I have no idea what this specific denial and disbelief costs
the United States, but a million dollars a day seems a modest
guess."

Page xxix in:

On the Cruelty of Really Teaching Computing Science

Edsger W. Dykstra (Dijkstra)

SIGCSE Bulletin 1989, 21(1), Page xxv-xxxix.
Also "www.cs.utexas.edu/users/EWD/"

#

  "Since breaking out of bad habits, rather than acquiring new
ones, is the toughest part of learning we must expect from that
system permanent mental damage for most students exposed to
it."

Page xxxvii in:

On the Cruelty of Really Teaching Computing Science

Edsger W. Dykstra (Dijkstra)

SIGCSE Bulletin 1989, 21(1), Page xxv-xxxix.
Also "www.cs.utexas.edu/users/EWD/"

#

  "The problems of the real world are primarily those you are
left with when you refuse to apply their effective solutions."

Page xxxviii in:

On the Cruelty of Really Teaching Computing Science

Edsger W. Dykstra (Dijkstra)

SIGCSE Bulletin 1989, 21(1), pages xxv-xxxix.
Also "www.cs.utexas.edu/users/EWD/"

#
	It is necessary to consider all consequences of
	the proposed action in all states of nature.

There are lots of consequences of any given action.  Many of the
problems of society today are at least partly due to the failure
to realize that the "obvious" action taken had so many bad side
effects.

Herman Rubin in the Usenet forum "misc.education.science".

  Add "not only for proposed actions but also for the actual (chosen)
actions"


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

-- 
Bjarni I. Gislason