good bug filing practices (Re: [bug #59424] ...)

[G. Branden Robinson]

[redirecting discussion to groff at gnu org, since I don't think of
bug-groff as really a discussion list]

At 2020-11-08T02:06:20+0000, Bjarni Ingi Gislason wrote:
> On Fri, Nov 06, 2020 at 05:59:16PM -0500, G. Branden Robinson wrote:
> > Update of bug #59424 (project groff):
> > [comment #0 original submission:]
> > > Subject: tmac/groff_mdoc.7.man: one table is wider than the line
> > > width (80)
> > > 
> > >   "man -l tmac/groff_mdoc.7.man"
> > 
> > I can't reproduce this, but as a point of general advice I don't
> > recommend running man directly on man pages in the groff source
> > tree, because they haven't gone through sed substitution (and, in
> > groff_man(7)'s case, digestion by m4).
> > 
> 
>   In this exceptional case both versions are the same.
> 
> I used the ".man" file to get the line number "correct", as I assumed,
> it could be (is) different from the file in the "build" directory.

That point is applicable to patches, but less so to problem reports,
where the exact situation as it would arise in the field should be
documented.

Granted, when we wear both developer and user hats for the same project,
lines can get a bit fuzzy.

> > > (using "test-nroff -mandoc -rF=0 -P-i -dAD=l -rHY=0")
> > 
> > This information is only partially helpful; "test-nroff" is not
> > something that is in public distribution or that anyone can be
> > expected to have (as far as I know, you're the only person on the
> > planet with such a script).  When reporting bugs, be sure you can
> > reproduce the problem exclusively using tools in general
> > distribution.
> > 
> 
>   I will add the content of my ~/.manpath to the error file from
>   "man", which is:
> 
> DEFINE        troff   test-groff -mandoc -rF=0
> DEFINE        nroff   test-nroff -mandoc -rF=0 -P-i -dAD=l -rHY=0
> # test-nroff is in my git/groff repository and is similar to "nroff"
> # there except "test-groff" is used instead of "groff".

The above would be a helpful reminder in future relevant reports, but
again, you should make sure you can reproduce it with standard tools.
We have no idea what your test-nroff executable contains.

> > Furthermore, the -rF=0 flag is spurious for this report.  I realize
> > that this option may be standard procedure for you to work around
> > other, less fastidious man pages, but when reporting a bug, a
> > _minimal_ reproducing case is of greater value.
> > 
> 
>   Yes, but for me, it is the minimal input (shortest input file).

I think there may be a misunderstanding here.  For _file_ input that
produces misbehavior, a minimal reproducing test case is indeed
valuable.  A minimal command line is a less sure thing, because Unix
shells have tons of state, are frequently customized in user
environments (largely through dot files like $HOME/.bashrc) and moreover
have multiple features that allow for elision of keystrokes.

You could have a one-letter shell alias (or shell function) called "m"
that does "test-nroff -mandoc -rF=0 -P-i -dAD=l -rHY=0", and I suspect
you'd agree that if your bug report simple said that you got the warning
when your minimal input was

  m groff_mdoc

that you haven't given us enough information to reproduce the problem.

Whatever will reproduce the problem with a "stock" configuration from a
major GNU/Linux or BSD distributor will probably serve well enough.  You
might consider creating a dummy or guinea pig account on your machine;
when you encounter problems, figure out how to reproduce it in the dummy
account without changing shell startup files or other dot files, writing
your own scripts or commands, and so forth.

That gives groff developers a better first shot at figuring out what's
going on.

> > Hmm, yes, I can't reproduce the problem even with -rLL=78n, the line
> > length man-db man(1) uses by default, and it is even shorter.
> > 
> 
>   I forgot to mention this in the environment:
> 
> MANOPT=-E latin1 --no-hyphenation --no-justification --warnings=w

Yes.  You have a _lot_ of customizations in your environment.  I don't
discourage that, but you should be aware that doing so interposes more
layers of processing between you and the result.  Many of these layers
will not be obvious to other people.  The dummy user account idea would
help here.

(Also, in my experience, more than once something I've thought was a bug
in vendor software was actually due to a customization I'd made in my
environment without fully understanding its consequences.)

>   There was a bug in my script causing "man" to use the installed
>   system files for the groff-related binaries (Debian package).
> 
>   After adding "~/git/groff/build" to the PATH, the same "filename"
>   was used in the warning.
> 
> "man" probably uses a different pipeline than "groff".
> 
>   "man -d ..." does not show the pipeline it constructs.

I've noticed that too.  I've dithered for literally years about filing a
bug report with Colin about it.  I shouldn't have to strace man to get
at what it finally eventually execve()s.

> N.B.  The GNU standard recommends:
> 
> "   Error messages from other noninteractive programs should look like
> this:
> 
>      PROGRAM:SOURCEFILE:LINENO: MESSAGE
> "
> 
>   The standard does not say what the "PROGRAM" should contain,
> but a sensible choice is
> 
>   1) the name of the binary that contains the MESSAGE,
> 
>   2) the name of the binary and the file,
> that contains the MESSAGE.
> 
> So reporting, who, where,and what.

This is sometimes not completely obvious.  I had a fairly different
analysis from yours in https://savannah.gnu.org/bugs/59443 for example.

>   I will add the value of the used character set with "locale -k
>   charmap" in the error file from "man".
> 
> (which is: charmap="ISO-8859-1".)

This is a really good idea since that encoding is far less widely used
than it used to be.

>   Thanks for your feedback.
> 
> N.B.  There is a typo (mistyping) in "lowecase pi".

Thanks for yours, and for your close reading, reminding me that I all
too often forget to turn on Vim's spell checker.

I fixed the typo in 041446555d4488d6d9f115dd488ed09a3f065078.

Regards,
Branden

signature.asc
Description: PGP signature