GNU bug report logs - #20403
Format of NEWS (navigating in it)

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 20403 in the body.
You can then email your comments to 20403 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: "Ulrich Windl" <Ulrich.Windl <at> rz.uni-regensburg.de>
To: <bug-gnu-emacs <at> gnu.org>
Subject: Format of NEWS (navigating in it)
Date: Wed, 22 Apr 2015 08:14:31 +0200

Hi!

As I was not running the latest version of Emacs, I started to read the NEWS file backwards (maybe life is just boring otherwise), beginning at the Emacs version I had before.
(while doing that the ghost of RMS appeared and asked: "Why don't you run the latest version when it's free?" ;-)
OK, serious again: I realized that when reading backwards it's rather hard to find out when you are done, because even that it's outline mode there is NOT ONE section per Emacs release (here 24.4) (with sub-sections), but multiple. To be concrete, the lop-level headings (when reading backwards) are:
* Changes in Emacs 24.4 on Non-Free Operating Systems
* Lisp Changes in Emacs 24.4
* Incompatible Lisp Changes in Emacs 24.4
* New Modes and Packages in Emacs 24.4
* Changes in Specialized Modes and Packages in Emacs 24.4
* Editing Changes in Emacs 24.4
* Changes in Emacs 24.4
(here I thought I'm done)
* Startup Changes in Emacs 24.4
* Installation Changes in Emacs 24.4

I know it's all a long tradition, but I'd prefer to have one major section per release. While re-discovering outline-mode, I also realized that C-c C-f [<outline-forward-same-level>] (and C-c C-b) have to be used twice to get to the next heading if an ASCII FF (form feed) (plus newline) character preceeds the heading.

Is this the way it should be?

Regards,
Ulrich

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

From: Stefan Kangas <stefan <at> marxist.se>
To: Ulrich Windl <Ulrich.Windl <at> rz.uni-regensburg.de>
Cc: 20403 <at> debbugs.gnu.org
Subject: Re: bug#20403: Format of NEWS (navigating in it)
Date: Mon, 30 Sep 2019 02:24:36 +0200

"Ulrich Windl" <Ulrich.Windl <at> rz.uni-regensburg.de> writes:

> Hi!
>
> As I was not running the latest version of Emacs, I started to read the NEWS file backwards (maybe life is just boring otherwise), beginning at the Emacs version I had before.
> (while doing that the ghost of RMS appeared and asked: "Why don't you run the latest version when it's free?" ;-)
> OK, serious again: I realized that when reading backwards it's rather hard to
> find out when you are done, because even that it's outline mode there is NOT ONE
> section per Emacs release (here 24.4) (with sub-sections), but multiple. To be
> concrete, the lop-level headings (when reading backwards) are:
> * Changes in Emacs 24.4 on Non-Free Operating Systems
> * Lisp Changes in Emacs 24.4
> * Incompatible Lisp Changes in Emacs 24.4
> * New Modes and Packages in Emacs 24.4
> * Changes in Specialized Modes and Packages in Emacs 24.4
> * Editing Changes in Emacs 24.4
> * Changes in Emacs 24.4
> (here I thought I'm done)
> * Startup Changes in Emacs 24.4
> * Installation Changes in Emacs 24.4
>
> I know it's all a long tradition, but I'd prefer to have one major section per
> release. While re-discovering outline-mode, I also realized that C-c C-f
> [<outline-forward-same-level>] (and C-c C-b) have to be used twice to get to the
> next heading if an ASCII FF (form feed) (plus newline) character preceeds the
> heading.
>
> Is this the way it should be?

I think this is the way it should be, yes.  It helps the user find
his/her way around the file.  Also note that these sections can
repeat, for example in etc/NEWS.24 we have:

* Changes in Emacs 24.5
* Changes in Emacs 24.4
* Changes in Emacs 24.3
* Changes in Emacs 24.2
* Changes in Emacs 24.1

Also, adding a new level means that each item would be preceded with
four stars in favour of three.

Are there any other opinions here?

Best regards,
Stefan Kangas

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

From: Stefan Kangas <stefan <at> marxist.se>
To: Ulrich Windl <Ulrich.Windl <at> rz.uni-regensburg.de>
Cc: 20403 <at> debbugs.gnu.org
Subject: Re: bug#20403: Format of NEWS (navigating in it)
Date: Wed, 30 Oct 2019 21:34:11 +0100

tags 20403 + wontfix
close 20403
thanks

Stefan Kangas <stefan <at> marxist.se> writes:

> "Ulrich Windl" <Ulrich.Windl <at> rz.uni-regensburg.de> writes:
>
>> Hi!
>>
>> As I was not running the latest version of Emacs, I started to read the NEWS file backwards (maybe life is just boring otherwise), beginning at the Emacs version I had before.
>> (while doing that the ghost of RMS appeared and asked: "Why don't you run the latest version when it's free?" ;-)
>> OK, serious again: I realized that when reading backwards it's rather hard to
>> find out when you are done, because even that it's outline mode there is NOT ONE
>> section per Emacs release (here 24.4) (with sub-sections), but multiple. To be
>> concrete, the lop-level headings (when reading backwards) are:
>> * Changes in Emacs 24.4 on Non-Free Operating Systems
>> * Lisp Changes in Emacs 24.4
>> * Incompatible Lisp Changes in Emacs 24.4
>> * New Modes and Packages in Emacs 24.4
>> * Changes in Specialized Modes and Packages in Emacs 24.4
>> * Editing Changes in Emacs 24.4
>> * Changes in Emacs 24.4
>> (here I thought I'm done)
>> * Startup Changes in Emacs 24.4
>> * Installation Changes in Emacs 24.4
>>
>> I know it's all a long tradition, but I'd prefer to have one major section per
>> release. While re-discovering outline-mode, I also realized that C-c C-f
>> [<outline-forward-same-level>] (and C-c C-b) have to be used twice to get to the
>> next heading if an ASCII FF (form feed) (plus newline) character preceeds the
>> heading.
>>
>> Is this the way it should be?
>
> I think this is the way it should be, yes.  It helps the user find
> his/her way around the file.  Also note that these sections can
> repeat, for example in etc/NEWS.24 we have:
>
> * Changes in Emacs 24.5
> * Changes in Emacs 24.4
> * Changes in Emacs 24.3
> * Changes in Emacs 24.2
> * Changes in Emacs 24.1
>
> Also, adding a new level means that each item would be preceded with
> four stars in favour of three.
>
> Are there any other opinions here?

No one else expressed an opinion within 4 weeks, so I'm closing this as
wontfix.

Best regards,
Stefan Kangas

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

From: Phil Sainty <psainty <at> orcon.net.nz>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: Ulrich Windl <Ulrich.Windl <at> rz.uni-regensburg.de>, 20403 <at> debbugs.gnu.org
Subject: Re: bug#20403: Format of NEWS (navigating in it)
Date: Thu, 31 Oct 2019 22:56:50 +1300

"Ulrich Windl" <Ulrich.Windl <at> rz.uni-regensburg.de> writes:
> I know it's all a long tradition, but I'd prefer to have one major
> section per release.

I'd be in favour of that myself (it does seem slightly cleaner), but
I'm also not especially bothered by the current format.


> While re-discovering outline-mode, I also realized that C-c C-f
> [<outline-forward-same-level>] (and C-c C-b) have to be used twice
> to get to the next heading if an ASCII FF (form feed) (plus newline)
> character preceeds the heading.

Note that the form feeds are there so that you can use page-based
commands.  e.g.:

C-x ] (forward-page)
C-x [ (backward-page)
C-x n p (narrow-to-page)

If I'm checking the history of something, I generally grep the NEWS
files, jump to the appropriate hit, and then use C-x [ to check
which specific version of Emacs that entry was for.


The change I'd actually like to see is for NEWS to just be a symlink
to the appropriate NEWS.xx file, which should exist under that name
from the outset of development on version xx.  That way every NEWS.xx
would contain its full history in version-control, rather than just
being a renamed NEWS with maybe a handful of retro-added additions.


-Phil

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Phil Sainty <psainty <at> orcon.net.nz>
Cc: Ulrich.Windl <at> rz.uni-regensburg.de, stefan <at> marxist.se, 20403 <at> debbugs.gnu.org
Subject: Re: bug#20403: Format of NEWS (navigating in it)
Date: Thu, 31 Oct 2019 16:43:50 +0200

> Date: Thu, 31 Oct 2019 22:56:50 +1300
> From: Phil Sainty <psainty <at> orcon.net.nz>
> Cc: Ulrich Windl <Ulrich.Windl <at> rz.uni-regensburg.de>, 20403 <at> debbugs.gnu.org
> 
> The change I'd actually like to see is for NEWS to just be a symlink
> to the appropriate NEWS.xx file, which should exist under that name
> from the outset of development on version xx.

That'd cause trouble when merging from the release branch.  Symlinks
complicate VCS operations in general.

If we want a better NEWS, I'd suggest to introduce a new mode, which
will inherit from Outline mode, but will support some sort of
"include" directive.  Then we could have a NEWS file that just
"include"d the versioned files, and Emacs would display their
contents, perhaps given some user command to expand a given version's
news.  As a bonus, this would let us have a single NEWS file, from
user's POV, like other (smaller) projects do.

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

From: Stefan Kangas <stefan <at> marxist.se>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: Phil Sainty <psainty <at> orcon.net.nz>,
 Ulrich Windl <Ulrich.Windl <at> rz.uni-regensburg.de>, 20403 <at> debbugs.gnu.org
Subject: Re: bug#20403: Format of NEWS (navigating in it)
Date: Thu, 31 Oct 2019 17:04:53 +0100

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

> > The change I'd actually like to see is for NEWS to just be a symlink
> > to the appropriate NEWS.xx file, which should exist under that name
> > from the outset of development on version xx.
>
> That'd cause trouble when merging from the release branch.  Symlinks
> complicate VCS operations in general.

Does that hold even if NEWS is a symlink also on the release branch?

If not, I'm thinking that the scripts for distributed tar balls could
then easily get rid of the symlink and move NEWS in place.

> If we want a better NEWS, I'd suggest to introduce a new mode, which
> will inherit from Outline mode, but will support some sort of
> "include" directive.  Then we could have a NEWS file that just
> "include"d the versioned files, and Emacs would display their
> contents, perhaps given some user command to expand a given version's
> news.  As a bonus, this would let us have a single NEWS file, from
> user's POV, like other (smaller) projects do.

That could also work.

(FWIW, I also think it would be nice to switch to org-mode.)

Best regards,
Stefan Kangas

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: psainty <at> orcon.net.nz, Ulrich.Windl <at> rz.uni-regensburg.de,
 20403 <at> debbugs.gnu.org
Subject: Re: bug#20403: Format of NEWS (navigating in it)
Date: Thu, 31 Oct 2019 18:11:26 +0200

> From: Stefan Kangas <stefan <at> marxist.se>
> Date: Thu, 31 Oct 2019 17:04:53 +0100
> Cc: Phil Sainty <psainty <at> orcon.net.nz>, Ulrich Windl <Ulrich.Windl <at> rz.uni-regensburg.de>, 
> 	20403 <at> debbugs.gnu.org
> 
> > That'd cause trouble when merging from the release branch.  Symlinks
> > complicate VCS operations in general.
> 
> Does that hold even if NEWS is a symlink also on the release branch?

Yes, because it's a symlink to a different file.

> (FWIW, I also think it would be nice to switch to org-mode.)

Yep.

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

From: Glenn Morris <rgm <at> gnu.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: Phil Sainty <psainty <at> orcon.net.nz>, Ulrich.Windl <at> rz.uni-regensburg.de,
 stefan <at> marxist.se, 20403 <at> debbugs.gnu.org
Subject: Re: bug#20403: Format of NEWS (navigating in it)
Date: Thu, 31 Oct 2019 15:19:40 -0400

>> The change I'd actually like to see is for NEWS to just be a symlink
>> to the appropriate NEWS.xx file, which should exist under that name
>> from the outset of development on version xx.
>
> That'd cause trouble when merging from the release branch.

I think the opposite.

At present, emacs26:etc/NEWS has to get merged to master:etc/NEWS.26.
This is a PITA at every single merge.

If the file was already called NEWS.26 on both branches,
all these merge problems would go away.

(This was previously proposed and rejected in https://debbugs.gnu.org/29366#30)

>  Symlinks complicate VCS operations in general.

Maybe on MS-Windows...

Maybe the etc/NEWS symlink doesn't even need to be versioned.
The build process could construct it based on the version number.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Glenn Morris <rgm <at> gnu.org>
Cc: psainty <at> orcon.net.nz, Ulrich.Windl <at> rz.uni-regensburg.de, stefan <at> marxist.se,
 20403 <at> debbugs.gnu.org
Subject: Re: bug#20403: Format of NEWS (navigating in it)
Date: Thu, 31 Oct 2019 22:08:26 +0200

> From: Glenn Morris <rgm <at> gnu.org>
> Cc: Phil Sainty <psainty <at> orcon.net.nz>,  Ulrich.Windl <at> rz.uni-regensburg.de,  stefan <at> marxist.se,  20403 <at> debbugs.gnu.org
> Date: Thu, 31 Oct 2019 15:19:40 -0400
> 
> At present, emacs26:etc/NEWS has to get merged to master:etc/NEWS.26.
> This is a PITA at every single merge.
> 
> If the file was already called NEWS.26 on both branches,
> all these merge problems would go away.

I proposed a solution to that which should make everybody happy.

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

From: Stefan Kangas <stefan <at> marxist.se>
To: Glenn Morris <rgm <at> gnu.org>
Cc: Phil Sainty <psainty <at> orcon.net.nz>, Eli Zaretskii <eliz <at> gnu.org>,
 20403 <at> debbugs.gnu.org, Ulrich Windl <Ulrich.Windl <at> rz.uni-regensburg.de>
Subject: Re: bug#20403: Format of NEWS (navigating in it)
Date: Fri, 1 Nov 2019 06:02:42 +0100

Glenn Morris <rgm <at> gnu.org> writes:

> Maybe the etc/NEWS symlink doesn't even need to be versioned.
> The build process could construct it based on the version number.

That makes sense to me.  When creating source distribution tarballs,
the file could simpy be copied or moved into place in case there are
problems with symlinks on this or that platform (I guess MS-Windows?).

Is there any reason not to do this?

Best regards,
Stefan Kangas

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: psainty <at> orcon.net.nz, rgm <at> gnu.org, Ulrich.Windl <at> rz.uni-regensburg.de,
 20403 <at> debbugs.gnu.org
Subject: Re: bug#20403: Format of NEWS (navigating in it)
Date: Fri, 01 Nov 2019 08:27:23 +0200

> From: Stefan Kangas <stefan <at> marxist.se>
> Date: Fri, 1 Nov 2019 06:02:42 +0100
> Cc: Eli Zaretskii <eliz <at> gnu.org>, Phil Sainty <psainty <at> orcon.net.nz>, 
> 	Ulrich Windl <Ulrich.Windl <at> rz.uni-regensburg.de>, 20403 <at> debbugs.gnu.org
> 
> Glenn Morris <rgm <at> gnu.org> writes:
> 
> > Maybe the etc/NEWS symlink doesn't even need to be versioned.
> > The build process could construct it based on the version number.
> 
> That makes sense to me.  When creating source distribution tarballs,
> the file could simpy be copied or moved into place in case there are
> problems with symlinks on this or that platform (I guess MS-Windows?).

Tarballs with symlinks are problematic, so I'm against having symlinks
in the release tarball.  But we could make NEWS a copy of the
corresponding NEWS.XY when we produce the tarball, if that's what
people prefer.

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

From: "Ulrich Windl" <Ulrich.Windl <at> rz.uni-regensburg.de>
To: <eliz <at> gnu.org>,<psainty <at> orcon.net.nz>
Cc: 20403 <at> debbugs.gnu.org, stefan <at> marxist.se
Subject: Antw: Re: bug#20403: Format of NEWS (navigating in it)
Date: Mon, 04 Nov 2019 08:16:57 +0100

>>> Eli Zaretskii <eliz <at> gnu.org> schrieb am 31.10.2019 um 15:43 in Nachricht
<83eeytnffd.fsf <at> gnu.org>:
>>  Date: Thu, 31 Oct 2019 22:56:50 +1300
>> From: Phil Sainty <psainty <at> orcon.net.nz>
>> Cc: Ulrich Windl <Ulrich.Windl <at> rz.uni‑regensburg.de>, 20403 <at> debbugs.gnu.org

>> 
>> The change I'd actually like to see is for NEWS to just be a symlink
>> to the appropriate NEWS.xx file, which should exist under that name
>> from the outset of development on version xx.
> 
> That'd cause trouble when merging from the release branch.  Symlinks
> complicate VCS operations in general.

ChangeLog-like files, especially when being more or less chronological always
cause trouble when merging, as merge itself is rarely chronological.
But for the topic: Having some "user-level symbolic links" like "See
NEWS-1.2.3" that Emacs can parse could be helpful, so (as proposed) the actual
"NEWS" would just contain a notice what the current versioned NEWS file is.
periodically renaming NEWS files (archiving unversioned to versioned) is
probably a bad idea.

> 
> If we want a better NEWS, I'd suggest to introduce a new mode, which
> will inherit from Outline mode, but will support some sort of
> "include" directive.  Then we could have a NEWS file that just
> "include"d the versioned files, and Emacs would display their
> contents, perhaps given some user command to expand a given version's
> news.  As a bonus, this would let us have a single NEWS file, from
> user's POV, like other (smaller) projects do.

Hmm:? Minor-mode "include-view" that presents a (read-only) view of a document
with all includes expanded. Actual include syntax would be delegated to some
functions or REGEXes...

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: "Ulrich Windl" <Ulrich.Windl <at> rz.uni-regensburg.de>
Cc: psainty <at> orcon.net.nz, 20403 <at> debbugs.gnu.org, stefan <at> marxist.se
Subject: Re: Antw: Re: bug#20403: Format of NEWS (navigating in it)
Date: Mon, 04 Nov 2019 18:11:14 +0200

> Date: Mon, 04 Nov 2019 08:16:57 +0100
> From: "Ulrich Windl" <Ulrich.Windl <at> rz.uni-regensburg.de>
> Cc: <20403 <at> debbugs.gnu.org>,<stefan <at> marxist.se>
> 
> ChangeLog-like files, especially when being more or less chronological always
> cause trouble when merging

NEWS is not a chronological file.  Its order is more or less random.

> > If we want a better NEWS, I'd suggest to introduce a new mode, which
> > will inherit from Outline mode, but will support some sort of
> > "include" directive.  Then we could have a NEWS file that just
> > "include"d the versioned files, and Emacs would display their
> > contents, perhaps given some user command to expand a given version's
> > news.  As a bonus, this would let us have a single NEWS file, from
> > user's POV, like other (smaller) projects do.
> 
> Hmm:? Minor-mode "include-view" that presents a (read-only) view of a document
> with all includes expanded. Actual include syntax would be delegated to some
> functions or REGEXes...

I cannot find include-view anywhere in Emacs.  What did I miss?

In any case, we need a derivative of Outline mode, so that readers
could fold and expand sub-entries.  The Emacs NEWS file is very large,
and most users aren't interested in every single piece of news.

Thanks.

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

From: Stefan Kangas <stefan <at> marxist.se>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: psainty <at> orcon.net.nz, rgm <at> gnu.org, Ulrich.Windl <at> rz.uni-regensburg.de,
 20403 <at> debbugs.gnu.org
Subject: Re: bug#20403: Format of NEWS (navigating in it)
Date: Mon, 11 Nov 2019 20:06:38 +0100

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

> But we could make NEWS a copy of the corresponding NEWS.XY when we
> produce the tarball, if that's what people prefer.

That sounds like a good solution to me.  Perhaps we can get the
machinery in place for Emacs 28.

Best regards,
Stefan Kangas

Previous Next

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