GNU bug report logs - #76901
[PATCH] ; * doc/emacs/trouble.texi (Coding Standards): Add manual reference

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 76901 in the body.
You can then email your comments to 76901 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Jeremy Bryant <jb <at> jeremybryant.net>
To: bug-gnu-emacs <at> gnu.org
Subject: [PATCH] ; * doc/emacs/trouble.texi (Coding Standards): Add manual
 reference
Date: Sun, 09 Mar 2025 22:29:51 +0000

[Message part 1 (text/plain, inline)]

The Emacs manual suggests that the GNU Coding Standards may be available
locally as an Info manual.
This patch inserts the explicit manual cross-reference.

It may be suitable as a documentation patch for the emacs-30 branch, or
otherwise for master.

Any comments please let me know.

[0001-doc-emacs-trouble.texi-Coding-Standards-Add-manual-r.patch (text/x-diff, attachment)]

Message #8 received at 76901 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefankangas <at> gmail.com>
To: Jeremy Bryant <jb <at> jeremybryant.net>, 76901 <at> debbugs.gnu.org
Cc: Eli Zaretskii <eliz <at> gnu.org>
Subject: Re: bug#76901: [PATCH] ; * doc/emacs/trouble.texi (Coding Standards):
 Add manual reference
Date: Sun, 9 Mar 2025 16:25:37 -0700

Jeremy Bryant via "Bug reports for GNU Emacs, the Swiss army knife of
text editors" <bug-gnu-emacs <at> gnu.org> writes:

> The Emacs manual suggests that the GNU Coding Standards may be available
> locally as an Info manual.
> This patch inserts the explicit manual cross-reference.
>
> It may be suitable as a documentation patch for the emacs-30 branch, or
> otherwise for master.
>
> Any comments please let me know.

I would guess that the reason why there is no reference is that most
GNU/Linux distributions do not distribute this Info manual, or at least
they don'tt by default or with commonly installed packages.

It's also never available as a printed manual, AFAIK.

I have no opinion on adding such a reference now.  Eli, WDYT?

Message #11 received at 76901 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefankangas <at> gmail.com>
Cc: jb <at> jeremybryant.net, 76901 <at> debbugs.gnu.org
Subject: Re: bug#76901: [PATCH] ; * doc/emacs/trouble.texi (Coding Standards):
 Add manual reference
Date: Mon, 10 Mar 2025 16:56:30 +0200

> From: Stefan Kangas <stefankangas <at> gmail.com>
> Date: Sun, 9 Mar 2025 16:25:37 -0700
> Cc: Eli Zaretskii <eliz <at> gnu.org>
> 
> Jeremy Bryant via "Bug reports for GNU Emacs, the Swiss army knife of
> text editors" <bug-gnu-emacs <at> gnu.org> writes:
> 
> > The Emacs manual suggests that the GNU Coding Standards may be available
> > locally as an Info manual.
> > This patch inserts the explicit manual cross-reference.
> >
> > It may be suitable as a documentation patch for the emacs-30 branch, or
> > otherwise for master.
> >
> > Any comments please let me know.
> 
> I would guess that the reason why there is no reference is that most
> GNU/Linux distributions do not distribute this Info manual, or at least
> they don'tt by default or with commonly installed packages.
> 
> It's also never available as a printed manual, AFAIK.
> 
> I have no opinion on adding such a reference now.  Eli, WDYT?

We have there a reference to the manual in HTML, isn't that enough?
In any case, having a URL and then a cross-reference to the Info
manuals in the next sentence sounds strange to me.  At the very least,
we should have there text saying that the manual can be either read
on-line in HTML format (with the URL), or locally in Info (with a Info
reference), to explain why we have both.

Message #16 received at 76901 <at> debbugs.gnu.org (full text, mbox):

From: Jeremy Bryant <jb <at> jeremybryant.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: Stefan Kangas <stefankangas <at> gmail.com>, 76901 <at> debbugs.gnu.org
Subject: Re: bug#76901: [PATCH] ; * doc/emacs/trouble.texi (Coding
 Standards): Add manual reference
Date: Tue, 11 Mar 2025 23:07:40 +0000

[Message part 1 (text/plain, inline)]

OK - Revised patch attached, reasoning below.

Eli Zaretskii <eliz <at> gnu.org> writes:

>> From: Stefan Kangas <stefankangas <at> gmail.com>
>> 
>> I would guess that the reason why there is no reference is that most
>> GNU/Linux distributions do not distribute this Info manual, or at least
>> they don'tt by default or with commonly installed packages.

Debian GNU/Linux includes it, in the gnu-standards package, which
includes both GNU standards and information for Maintainers, available
in Info, HTML, PDF.


File list of package gnu-standards:

/usr/share/doc-base/gnu-standards.gnu-coding-standards
/usr/share/doc-base/gnu-standards.gnu-maintainers-information
/usr/share/doc/gnu-standards/changelog.Debian.gz
/usr/share/doc/gnu-standards/changelog.gz
/usr/share/doc/gnu-standards/copyright
/usr/share/doc/gnu-standards/maintain.dvi.gz
/usr/share/doc/gnu-standards/maintain.html
/usr/share/doc/gnu-standards/maintain.pdf.gz
/usr/share/doc/gnu-standards/maintain.text.gz
/usr/share/doc/gnu-standards/standards.dvi.gz
/usr/share/doc/gnu-standards/standards.html
/usr/share/doc/gnu-standards/standards.pdf.gz
/usr/share/doc/gnu-standards/standards.text.gz
/usr/share/info/maintain.info.gz
/usr/share/info/standards.info.gz

AFAICT, other Debian derivatives such as Ubuntu have the same package.
The upstream GNU package is gnustandards
https://directory.fsf.org/wiki/Gnustandards

Guix also includes gnustandards, which like other Guix packages can be
installed on top of any other GNU/Linux distribution.

>> 
>> It's also never available as a printed manual, AFAIK.
>> 
>> I have no opinion on adding such a reference now.  Eli, WDYT?
>
> We have there a reference to the manual in HTML, isn't that enough?

IMHO we should try to have GNU documentation available locally,
encourage access locally, not just over the web, for the sake of user
freedom.
There are also practical considerations, such as users on laptops
travelling without a network connection.


> In any case, having a URL and then a cross-reference to the Info
> manuals in the next sentence sounds strange to me.  At the very least,
> we should have there text saying that the manual can be either read
> on-line in HTML format (with the URL), or locally in Info (with a Info
> reference), to explain why we have both.

I accept that, and attach a revised patch with the changes made.  Any
further work please let me know.

[0001-doc-emacs-trouble.texi-Coding-Standards-Add-manual-r.patch (text/x-diff, attachment)]

Message #19 received at 76901 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefankangas <at> gmail.com>
To: Jeremy Bryant <jb <at> jeremybryant.net>, Eli Zaretskii <eliz <at> gnu.org>
Cc: 76901 <at> debbugs.gnu.org
Subject: Re: bug#76901: [PATCH] ; * doc/emacs/trouble.texi (Coding Standards):
 Add manual reference
Date: Tue, 11 Mar 2025 19:32:59 -0400

Jeremy Bryant <jb <at> jeremybryant.net> writes:

> Eli Zaretskii <eliz <at> gnu.org> writes:
>
>>> From: Stefan Kangas <stefankangas <at> gmail.com>
>>>
>>> I would guess that the reason why there is no reference is that most
>>> GNU/Linux distributions do not distribute this Info manual, or at least
>>> they don'tt by default or with commonly installed packages.
>
> Debian GNU/Linux includes it, in the gnu-standards package, which
> includes both GNU standards and information for Maintainers, available
> in Info, HTML, PDF.

[...]

> AFAICT, other Debian derivatives such as Ubuntu have the same package.
> The upstream GNU package is gnustandards
> https://directory.fsf.org/wiki/Gnustandards
>
> Guix also includes gnustandards, which like other Guix packages can be
> installed on top of any other GNU/Linux distribution.

That's encouraging.

>>> It's also never available as a printed manual, AFAIK.
>>>
>>> I have no opinion on adding such a reference now.  Eli, WDYT?
>>
>> We have there a reference to the manual in HTML, isn't that enough?
>
> IMHO we should try to have GNU documentation available locally,
> encourage access locally, not just over the web, for the sake of user
> freedom.
> There are also practical considerations, such as users on laptops
> travelling without a network connection.

All valid points, of course.

> From 513fbf407ebea1681637cc38dad1a0cfd91c5552 Mon Sep 17 00:00:00 2001
> From: Jeremy Bryant <jb <at> jeremybryant.net>
> Date: Sun, 9 Mar 2025 22:25:03 +0000
> Subject: [PATCH] ; * doc/emacs/trouble.texi (Coding Standards): Add manual
>  reference
>
> ---
>  doc/emacs/trouble.texi | 7 ++++---
>  1 file changed, 4 insertions(+), 3 deletions(-)
>
> diff --git a/doc/emacs/trouble.texi b/doc/emacs/trouble.texi
> index 2211369b121..95860e9f00f 100644
> --- a/doc/emacs/trouble.texi
> +++ b/doc/emacs/trouble.texi
> @@ -1494,9 +1494,10 @@ Coding Standards
>  @subsection Coding Standards
>  @cindex coding standards for Emacs submissions
>
> -Contributed code should follow the GNU Coding Standards
> -@url{https://www.gnu.org/prep/standards/}.  This may also be available
> -in info on your system.
> +Contributed code should follow the GNU Coding Standards.  This manual
> +is available on-line at @url{https://www.gnu.org/prep/standards/}.  It
> +may also be available locally in Info on your system, see @pxref{Top,,,
> +standards, GNU Coding Standards}.

LGTM, but let's wait to see what Eli says.

>
>  If it doesn't, we'll need to find someone to fix the code before we
>  can use it.
> --
> 2.47.2

Message #22 received at 76901 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefankangas <at> gmail.com>
Cc: jb <at> jeremybryant.net, 76901 <at> debbugs.gnu.org
Subject: Re: bug#76901: [PATCH] ; * doc/emacs/trouble.texi (Coding Standards):
 Add manual reference
Date: Wed, 12 Mar 2025 15:22:16 +0200

> From: Stefan Kangas <stefankangas <at> gmail.com>
> Date: Tue, 11 Mar 2025 19:32:59 -0400
> Cc: 76901 <at> debbugs.gnu.org
> 
> Jeremy Bryant <jb <at> jeremybryant.net> writes:
> 
> > diff --git a/doc/emacs/trouble.texi b/doc/emacs/trouble.texi
> > index 2211369b121..95860e9f00f 100644
> > --- a/doc/emacs/trouble.texi
> > +++ b/doc/emacs/trouble.texi
> > @@ -1494,9 +1494,10 @@ Coding Standards
> >  @subsection Coding Standards
> >  @cindex coding standards for Emacs submissions
> >
> > -Contributed code should follow the GNU Coding Standards
> > -@url{https://www.gnu.org/prep/standards/}.  This may also be available
> > -in info on your system.
> > +Contributed code should follow the GNU Coding Standards.  This manual
> > +is available on-line at @url{https://www.gnu.org/prep/standards/}.  It
> > +may also be available locally in Info on your system, see @pxref{Top,,,
> > +standards, GNU Coding Standards}.
> 
> LGTM, but let's wait to see what Eli says.

I say LGTM, thanks.

Message #27 received at 76901-done <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefankangas <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: jb <at> jeremybryant.net, 76901-done <at> debbugs.gnu.org
Subject: Re: bug#76901: [PATCH] ; * doc/emacs/trouble.texi (Coding Standards):
 Add manual reference
Date: Wed, 12 Mar 2025 23:15:07 -0700

Version: 30.2

Eli Zaretskii <eliz <at> gnu.org> writes:

>> From: Stefan Kangas <stefankangas <at> gmail.com>
>> Date: Tue, 11 Mar 2025 19:32:59 -0400
>> Cc: 76901 <at> debbugs.gnu.org
>>
>> Jeremy Bryant <jb <at> jeremybryant.net> writes:
>>
>> > diff --git a/doc/emacs/trouble.texi b/doc/emacs/trouble.texi
>> > index 2211369b121..95860e9f00f 100644
>> > --- a/doc/emacs/trouble.texi
>> > +++ b/doc/emacs/trouble.texi
>> > @@ -1494,9 +1494,10 @@ Coding Standards
>> >  @subsection Coding Standards
>> >  @cindex coding standards for Emacs submissions
>> >
>> > -Contributed code should follow the GNU Coding Standards
>> > -@url{https://www.gnu.org/prep/standards/}.  This may also be available
>> > -in info on your system.
>> > +Contributed code should follow the GNU Coding Standards.  This manual
>> > +is available on-line at @url{https://www.gnu.org/prep/standards/}.  It
>> > +may also be available locally in Info on your system, see @pxref{Top,,,
>> > +standards, GNU Coding Standards}.
>>
>> LGTM, but let's wait to see what Eli says.
>
> I say LGTM, thanks.

Thanks, installed on emacs-30 as [1: f729828bcfb].

[1: f729828bcfb] 2025-03-13
  ; Add texinfo reference to GNU Coding Standards.
  https://git.savannah.gnu.org/cgit/emacs.git/commit/?id=f729828bcfbca8e972467ace85dd32744e4dd6de

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.