bugGNU roff - Bugs: bug #54910, much documentation still...

 
 

bug #54910: much documentation still recommends bug-groff@gnu.org for filing bug reports

Submitter:  Dave <barx>
Submitted:  Mon 29 Oct 2018 05:30:31 AM UTC
   
 
Category:  General Severity:  3 - Normal
Item Group:  Documentation Status:  Fixed
Privacy:  Public Assigned to:  gbranden
Open/Closed:  Closed Planned Release:  1.22.4
* Mandatory Fields

Add a New Comment Rich Markup
   

Jump to the original submission

Wed 15 Jun 2022 06:38:37 PM UTC, comment #9: 

It appears this was never explicitly addressed:

comment #2:

> I changed the address to that of the groff discussion list.
> (However, I don't know whether this list is configured to accept
> email from nonsubscribers, so this may not be a viable change.)


The groff@ list's "Privacy options -> Sender filters" administration page says that email from nonsubscribers is currently put in a moderation queue.  So anything that's not spam or wildly off topic will get approved.

Dave <barx>
Group Member
Wed 15 Jun 2022 05:31:47 PM UTC, comment #8: 


commit 81f7ba3bc0b8fa06ce64dec0eb4a12639abd35a7
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Tue Nov 6 08:52:22 2018 -0500

    Remove instructions to file bugs via bug-groff.

            Patch courtesy of Dave Kemper.  His comments, massaged into GNU
            changelog format, follow.

            [The patch] also fixes a couple of trivial errors in grammar,
            punctuation, etc., that I spotted in the process[].

            * PROJECTS: Since the context of bug-groff@gnu.org in this file
            is not reporting bugs, instead of changing it to point to the
            bug tracker, I changed the address to that of the groff
            discussion list.  (However, I don't know whether this list is
            configured to accept email from nonsubscribers, so this may not
            be a viable change.)

            * README:
            * doc/webpage.ms: These files already recommended the bug tracker
            as the bug-reporting mechanism; they said using the method in
            the file BUG-REPORT was an alternative.  As BUG-REPORT also now
            points to the bug tracker, I've tweaked this wording.

            * doc/groff.texi: The address bug-groff@gnu.org was used only
            once in this file, not as an address to report bugs, but as the
            email address for Werner Lemberg.  I would take this to mean he
            doesn't want his actual email address in public documentation,
            except that it appears in many other places throughout groff
            source code and documentation alike.  So it doesn't seem
            unreasonable to put it in this file as well.  I will email him
            to confirm that this is OK. [I went ahead and removed it; we
            don't need an email address in the document, IMO. --GBR]

            * INSTALL.extra: Like README, this cited the file BUG-REPORT as
            an alternative mechanism. I removed this wording entirely.

            * BUG-REPORT:
            * contrib/groffer/README:
            * contrib/mm/README:
            * contrib/mm/m.tmac:
            * contrib/mm/mm/0.MT:
            * contrib/mm/mm/4.MT:
            * contrib/mm/mm/5.MT:
            * contrib/mm/mm/ms.cov:
            * contrib/mm/mse.tmac:
            * src/devices/xditview/README: Tweak wording and direct readers
            to Savannah bug tracker instead of bug-groff mailing list.

commit f7a3924b6c841df62475df4900c4d21fdd03ba41
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Sun Nov 11 18:35:38 2018 -0500

    configure.ac: Submit bugs via Web, not email.

            Continues fixing <https://savannah.gnu.org/bugs/?54910>.


G. Branden Robinson <gbranden>
Group administrator
Sun 11 Nov 2018 11:45:06 PM UTC, comment #7: 

AC_INIT is now also updated to send people to the Web, as of f7a3924b6c841df62475df4900c4d21fdd03ba41.

G. Branden Robinson <gbranden>
Group administrator
Wed 07 Nov 2018 01:02:37 AM UTC, comment #6: 

Also, for anyone browsing this bug report in the future, part of its fix is in the commit cited in comment #4, and part in commit 7908dc1dcfcb0b93fe5d35269db92702d28bc1f4.

Dave <barx>
Group Member
Tue 06 Nov 2018 09:30:01 PM UTC, comment #5: 

Sounds good.  For the record, Werner is OK with the change to doc/groff.texi (though I probably should have asked him to post that here so his acquiescence would be publicly visible).

Dave <barx>
Group Member
Tue 06 Nov 2018 02:32:20 PM UTC, comment #4: 

Fixed in 81f7ba3bc0b8fa06ce64dec0eb4a12639abd35a7.

G. Branden Robinson <gbranden>
Group administrator
Tue 06 Nov 2018 01:41:38 PM UTC, comment #3: 

Thanks, Dave!

My autoconf/Makefile solution might be overkill.  Only about 7 of 61 man page sources even mentioned the bug-groff list.  Several more pages have a BUGS section, but it's used more for the classical purpose of documenting existing problems.

For now I'm just going to chop out "please report bugs this way" material from the man pages, and see if that flies with the mailing list.  If we want a way to boilerplate a reference to Savannah and/or bug-reporting instructions into all 61 pages, I can work on that.

I'm queueing up your changes now.  Thanks again!

G. Branden Robinson <gbranden>
Group administrator
Tue 06 Nov 2018 11:44:08 AM UTC, comment #2: 

Yes, your autoconf solution seems like the best fit for the man pages.  I was unaware of this feature of autoconf.

Being wholly unfamiliar with groff's build process, it's best that I not attempt to change any autoconf files or Makefiles, lest I break the build.

But I have updated the remaining files you mention and attached a patch (which also fixes a couple of trivial errors in grammar, punctuation, etc., that I spotted in the process).  Some specific notes on five of these files:

NEWS

I did not update this file; its one reference to -email is unavailable- is under the "VERSION 1.17" section, and I'm not sure it makes sense to modify that at this point.

PROJECTS

Since the context of -email is unavailable- in this file is not reporting bugs, instead of changing it to point to the bug tracker, I changed the address to that of the groff discussion list.  (However, I don't know whether this list is configured to accept email from nonsubscribers, so this may not be a viable change.)

README, doc/webpage.ms

These files already recommended the bug tracker as the bug-reporting mechanism; they said using the method in the file BUG-REPORT was an alternative.  As BUG-REPORT also now points to the bug tracker, I've tweaked this wording.

doc/groff.texi

The address -email is unavailable- was used only once in this file, not as an address to report bugs, but as the email address for Werner Lemberg.  I would take this to mean he doesn't want his actual email address in public documentation, except that it appears in many other places throughout groff source code and documentation alike.  So it doesn't seem unreasonable to put it in this file as well.  I will email him to confirm that this is OK.

Additionally, I modified INSTALL.extra: Like README, this cited the file BUG-REPORT as an alternative mechanism.  I removed this wording entirely.

(file #45371)

Dave <barx>
Group Member
Sun 04 Nov 2018 08:13:16 AM UTC, comment #1: 

I'm thinking the best thing to do here is leverage the Autoconf variable PACKAGE_BUGREPORT.

First we'd need to update configure.ac to move to the URL instead of the email address.

Then we need to update Makefile.am to do a sed substitution in the man pages, similar to @MACRODIR@.

Then the man pages that refer to bug-groff need to be updated to use @PACKAGE_BUGREPORT@ string instead.  Unfortunately, we'd violate the abstraction layering here by having to know whether to use .MT/.ME or .UR/.UE macros to mark it up with. At the cost of greater complexity, we could solve this by making a more complex substitution in Makefile.am.

That leaves the following:
BUG-REPORT
NEWS
PROJECTS
README
contrib/groffer/README
contrib/mm/README
contrib/mm/m.tmac
contrib/mm/mm/0.MT
contrib/mm/mm/4.MT
contrib/mm/mm/5.MT
contrib/mm/mm/ms.cov
contrib/mm/mse.tmac
doc/groff.texi
doc/webpage.ms
src/devices/xditview/README

G. Branden Robinson <gbranden>
Group administrator
Mon 29 Oct 2018 05:30:31 AM UTC, original submission:  

The groff documentation should point to this bug tracker as the preferred place to report bugs.  Most of the documentation currently points to bug-groff@gnu.org, but issues sent there that aren't addressed right away are likely to get lost.

Running this command in the top-level groff source directory:

  find . -type f -exec egrep 'bug\\?-groff[@ ]' {} \; | wc -l

shows 28 results.  Not all of these needs to be changed, but many do.

This is an edit I can make myself and submit a patch for.  This will take a little time, and I wanted to put the issue in the bug tracker first, even without a patch, so that there's a record of it.

Dave <barx>
Group Member

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:
   
   
Comment:
   

Attached Files
file #45371:  buggroff.patch added by barx (12KiB - text/x-patch)

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by gbranden (Posted a comment)
  • -email is unavailable- added by barx (Submitted the item)
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only logged-in users can vote.

     

    Follow 8 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2022-06-15 gbranden CategoryNone General
    2018-11-06 gbranden StatusIn Progress Fixed
        Open/ClosedOpen Closed
        Planned ReleaseNone 1.22.4
    2018-11-06 gbranden StatusConfirmed In Progress
    2018-11-06 barx Attached File- Added buggroff.patch, #45371
    2018-11-04 gbranden StatusNone Confirmed
        Assigned toNone gbranden

    Back to the top

    Powered by Savane 3.13-aa77.
    Corresponding source code