Organizing the NEWS file a bit better

Organizing the NEWS file a bit better

[Stefan Kangas]

I'm looking at re-organizing NEWS a bit, and I'm not sure how we prefer it.

In general, I guess I also wonder if anyone will protest if I take it
upon myself to move things around to more sensible places.

Here are some concrete questions:

- Under "Changes in Specialized Modes and Packages" things seem thrown
  in more or less at random.  Do we prefer to order it according to
  perceived order of importance?  Would it make sense to organize it
  alphabetically?

- Does "Tab Bars" belong under "Changes in Emacs" rather than
  "Specialized Modes"?  It's more like a core feature to my mind, even
  if not everyone uses it.  (I've moved "Windows" and "Frames" there
  already.)

- Under "Incompatible Editing Changes" we have several items relating
  to specialized modes (f90-mode, nroff-mode, vc, project).  Do these
  entries belong under "Specialized Modes and Packages"?

- Could we just put new headers for macOS and MS-Windows under "Emacs
  28.1 on Non-Free Operating Systems"?  Entries now start with "On
  macOS ..." or "On MS-Windows ...", which we could avoid.

- Under "Editing Changes" we have many things that doesn't seem like
  they belong there.  Should they be moved?  See the list below where
  I've marked things that we might want to move with "x".

  * Editing Changes in Emacs 28.1
x ** New value 'save-some-buffers-root' of
'save-some-buffers-default-predicate'.
x ** Dragging a file to Emacs will now also push the name of the file
  ** Menus
x *** New minor mode 'context-menu-mode' for context menus popped by 'mouse-3'.
  *** The "Edit => Clear" menu item now obeys a rectangular region.
  ** New command 'execute-extended-command-for-buffer'.
  ** New user option 'read-extended-command-predicate'.
x ** 'eval-expression' now no longer signals an error on incomplete expressions.
x ** 'eval-last-sexp' now handles 'defvar'/'defcustom'/'defface' specially.
  ** Standalone 'M-y' allows interactive selection from previous kills.
x ** New user options 'copy-region-blink-delay' and 'delete-pair-blink-delay'.
  ** New command 'undo-redo'.
x ** 'read-number' now has its own history variable.
  ** Input history for 'goto-line' can now be made local to every buffer.
  ** New command 'goto-line-relative' to use in a narrowed buffer.
  ** When called interactively, 'goto-char' now offers the number at
x ** When 'suggest-key-bindings' is non-nil, the completion list of 'M-x'
  ** Autosaving via 'auto-save-visited-mode' can now be inhibited by
x ** New commands to describe buttons and widgets have been added.
x ** Obsolete aliases are no longer hidden from command completion.
  ** New command 'revert-buffer-with-fine-grain'.
  ** New command 'memory-report'.
  ** New user option 'isearch-repeat-on-direction-change'.
  ** New commands 'copy-matching-lines' and 'kill-matching-lines'.
  ** Setting 'fill-column' to nil is obsolete.

Re: Organizing the NEWS file a bit better

[Lars Ingebrigtsen]

Stefan Kangas <stefan@marxist.se> writes:

> I'm looking at re-organizing NEWS a bit, and I'm not sure how we prefer it.
>
> In general, I guess I also wonder if anyone will protest if I take it
> upon myself to move things around to more sensible places.

Please go ahead.  When adding NEWS-worthy things, they generally land
somewhere in the general section where they should be, not organised
further than that.  (I try to see if there's something already in NEWS
that's about the same package, and then create a sub-section for
that...  but not methodically.)

> Here are some concrete questions:
>
> - Under "Changes in Specialized Modes and Packages" things seem thrown
>   in more or less at random.  Do we prefer to order it according to
>   perceived order of importance?  Would it make sense to organize it
>   alphabetically?

I have no opinion about that.

> - Does "Tab Bars" belong under "Changes in Emacs" rather than
>   "Specialized Modes"?  It's more like a core feature to my mind, even
>   if not everyone uses it.  (I've moved "Windows" and "Frames" there
>   already.)

Yes, sounds like a "Changes in Emacs" thing, I think.

> - Under "Incompatible Editing Changes" we have several items relating
>   to specialized modes (f90-mode, nroff-mode, vc, project).  Do these
>   entries belong under "Specialized Modes and Packages"?

Uhm...  I think it makes sense to have the incompatible stuff in one
section?  It makes it easy for people who only want to know what might
have broken in their code.

> - Could we just put new headers for macOS and MS-Windows under "Emacs
>   28.1 on Non-Free Operating Systems"?  Entries now start with "On
>   macOS ..." or "On MS-Windows ...", which we could avoid.

Sounds good.

> - Under "Editing Changes" we have many things that doesn't seem like
>   they belong there.  Should they be moved?  See the list below where
>   I've marked things that we might want to move with "x".

Hm...  where would you move them to?  "Changes in Emacs"?  I think most
of the "x" things might live more comfortably there, perhaps?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: Organizing the NEWS file a bit better

[Juri Linkov]

> I'm looking at re-organizing NEWS a bit, and I'm not sure how we prefer it.
>
> In general, I guess I also wonder if anyone will protest if I take it
> upon myself to move things around to more sensible places.
>
> Here are some concrete questions:
>
> - Does "Tab Bars" belong under "Changes in Emacs" rather than
>   "Specialized Modes"?  It's more like a core feature to my mind, even
>   if not everyone uses it.  (I've moved "Windows" and "Frames" there
>   already.)

OT1H, tab-bar-mode and tab-line-mode are specialized modes.  OTOH,
they are related to frames and windows.

Re: Organizing the NEWS file a bit better

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Sat, 4 Sep 2021 20:53:22 +0200
> 
> In general, I guess I also wonder if anyone will protest if I take it
> upon myself to move things around to more sensible places.

No one will protest if you do it right ;-)

> - Under "Changes in Specialized Modes and Packages" things seem thrown
>   in more or less at random.  Do we prefer to order it according to
>   perceived order of importance?

More or less, yes.  However, this is not always easy, so just make
sure that definitely important stuff comes before the rest.

>   Would it make sense to organize it alphabetically?

No, because no one will look for items one by one.  If you are after a
specific item, you will just use C-s.

> - Under "Incompatible Editing Changes" we have several items relating
>   to specialized modes (f90-mode, nroff-mode, vc, project).  Do these
>   entries belong under "Specialized Modes and Packages"?

I agree with Lars that calling out incompatible changes is more
important than having them together with other related items.

Thanks.

Re: Organizing the NEWS file a bit better

[Stefan Kangas]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Please go ahead.  When adding NEWS-worthy things, they generally land
> somewhere in the general section where they should be, not organised
> further than that.  (I try to see if there's something already in NEWS
> that's about the same package, and then create a sub-section for
> that...  but not methodically.)

Right.  My motivation for looking at this was basically that I've been
mostly inactive for a bit, and had to catch up, and that the next
Emacs release is approaching.

> > - Under "Incompatible Editing Changes" we have several items relating
> >   to specialized modes (f90-mode, nroff-mode, vc, project).  Do these
> >   entries belong under "Specialized Modes and Packages"?
>
> Uhm...  I think it makes sense to have the incompatible stuff in one
> section?  It makes it easy for people who only want to know what might
> have broken in their code.

Makes sense, and it seems like Eli agrees too.

> > - Under "Editing Changes" we have many things that doesn't seem like
> >   they belong there.  Should they be moved?  See the list below where
> >   I've marked things that we might want to move with "x".
>
> Hm...  where would you move them to?  "Changes in Emacs"?  I think most
> of the "x" things might live more comfortably there, perhaps?

Yup, that's where I'd put them, based on skimming the headers.  I'll
take a closer look, and if someone disagrees with my changes they
should feel free to move the entries again.

Re: Organizing the NEWS file a bit better

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> > In general, I guess I also wonder if anyone will protest if I take it
> > upon myself to move things around to more sensible places.
>
> No one will protest if you do it right ;-)

I'll do my best!  ;-)

> > - Under "Changes in Specialized Modes and Packages" things seem thrown
> >   in more or less at random.  Do we prefer to order it according to
> >   perceived order of importance?
>
> More or less, yes.  However, this is not always easy, so just make
> sure that definitely important stuff comes before the rest.

Makes sense, thanks.

Re: Organizing the NEWS file a bit better

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Sat, 4 Sep 2021 21:34:33 +0200
> Cc: Emacs developers <emacs-devel@gnu.org>
> 
> > > - Under "Editing Changes" we have many things that doesn't seem like
> > >   they belong there.  Should they be moved?  See the list below where
> > >   I've marked things that we might want to move with "x".
> >
> > Hm...  where would you move them to?  "Changes in Emacs"?  I think most
> > of the "x" things might live more comfortably there, perhaps?
> 
> Yup, that's where I'd put them, based on skimming the headers.

Some of them sound more like Lisp Changes to me, so look out.

Re: Organizing the NEWS file a bit better

[Tim Cross]

Lars Ingebrigtsen <larsi@gnus.org> writes:

>> - Under "Incompatible Editing Changes" we have several items relating
>>   to specialized modes (f90-mode, nroff-mode, vc, project).  Do these
>>   entries belong under "Specialized Modes and Packages"?
>
> Uhm...  I think it makes sense to have the incompatible stuff in one
> section?  It makes it easy for people who only want to know what might
> have broken in their code.
>

I think this is an important one. My 'use case' for looking in NEWS is

1. See what has changed and may require that I review/update my
configuration. I might read this before upgrading or immediately after.
Being able to identify a specific section which alerts me to
incompatible changes is important.

2. When I find something not working after an upgrade, I will look to
see if some change may have occurred. For this use case, I tend to use
C-s and search for specific keywords rather than general reading of the
file. Anything which would help in this regard would be useful. 

Re: Organizing the NEWS file a bit better

[Stefan Kangas]

Tim Cross <theophilusx@gmail.com> writes:

> I think this is an important one. My 'use case' for looking in NEWS is
>
> 1. See what has changed and may require that I review/update my
> configuration. I might read this before upgrading or immediately after.
> Being able to identify a specific section which alerts me to
> incompatible changes is important.

Yup, it seems like we all agree about keeping this section as is.

> 2. When I find something not working after an upgrade, I will look to
> see if some change may have occurred. For this use case, I tend to use
> C-s and search for specific keywords rather than general reading of the
> file. Anything which would help in this regard would be useful.

Thanks.  Your use-case is different from mine, which is to carefully
review the file from top to bottom.  (I understand that we can't
realistically expect most users to do that.)

I'm not sure what we could do to improve searching, but ideas are
welcome of course.

Re: Organizing the NEWS file a bit better

[Stefan Kangas]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> > I'm looking at re-organizing NEWS a bit, and I'm not sure how we prefer it.
> >
> > In general, I guess I also wonder if anyone will protest if I take it
> > upon myself to move things around to more sensible places.
>
> Please go ahead.

I have now pushed my reorganization of the NEWS file to master.

Note that the changes were necessarily extensive, as a large portion
of that file was in completely the wrong place, or at worst seemed to
have been placed almost at random.  This is not to criticize anyone,
but really it just looks like the file started getting messy at some
point and then it snowballed from there.

None of the changes should be controversial, as it was just a matter
trying to ensure we have some basic level of organization in the file.
I've decided to push what I have so far, because I need a pause from
this, and I don't want master to diverge too much from what I have.

I tried to follow some general principles, for example:

- Avoid editing beyond moving things around, unless the edits are very,
  very light.

- Add subsections where it makes sense.  Remove them where it doesn't.

- Put the most notable changes as early as possible.  For example,
  under "Changes in Emacs 28.1" I have a new subsection
  "Miscellaneous" that has many bits and pieces that I didn't feel
  deserve a place at the top.  But I moved NonGNU ELPA to the very
  top.

- Put obviously less used or less important things last.  For example,
  I put Bindat at the end of "Lisp Changes" as it is only used by a
  small number of packages.

- Put related things close whenever possible.

Some of this is by nature subjective.  I did the work, so I got to
decide (yay!) but if you feel like I made a mistake or wrote some
important feature off or something, please shuffle things around to be
better.

I tried hard to ensure nothing was lost,[1] but if you want to check
this yourself you could use, e.g.:

    comm -3 <(git show HEAD^:etc/NEWS|sort) <(sort etc/NEWS)

If anyone wants to review my changes in full, I suspect you will find
the diff to be very hard to read.  It might be easier to just read the
new file and compare it to the old one.

Reviews are welcome, preferably in the form of just pushing any
further changes to master.

Footnotes:
[1] I have advocated in the past for marking documentation changes
     using org-mode style tags.  This would mean that you add a tag
     like ":DOC:" on the same line as a headline, instead of "+++" on
     the line before.  That way, one could edit the file using
     'outline-move-subtree-{up,down}'.  That would have made this
     reorganization quite a bit easier.

Re: Organizing the NEWS file a bit better

[Jean-Christophe Helary]

> On Sep 6, 2021, at 11:30, Stefan Kangas <stefan@marxist.se> wrote:
> 
> Lars Ingebrigtsen <larsi@gnus.org> writes:
> 
>>> I'm looking at re-organizing NEWS a bit, and I'm not sure how we prefer it.
>>> 
>>> In general, I guess I also wonder if anyone will protest if I take it
>>> upon myself to move things around to more sensible places.
>> 
>> Please go ahead.
> 
> I have now pushed my reorganization of the NEWS file to master.

It looks very nice, especially read as an org-mode file.
And sorting the info makes for a much more informative experience.

Thank you.

-- 
Jean-Christophe Helary @brandelune
https://mac4translators.blogspot.com
https://sr.ht/~brandelune/omegat-as-a-book/

Re: Organizing the NEWS file a bit better

[Juri Linkov]

> I have now pushed my reorganization of the NEWS file to master.

Thanks, now it's much better.

> I tried hard to ensure nothing was lost,[1] but if you want to check
> this yourself you could use, e.g.:
>
>     comm -3 <(git show HEAD^:etc/NEWS|sort) <(sort etc/NEWS)

This shows that 'benchmark-call' is lost (I don't know if it needs a NEWS entry).

> Reviews are welcome, preferably in the form of just pushing any
> further changes to master.

I pushed only a small adjustment to "Isearch and Replace".

> Footnotes:
> [1] I have advocated in the past for marking documentation changes
>      using org-mode style tags.  This would mean that you add a tag
>      like ":DOC:" on the same line as a headline, instead of "+++" on
>      the line before.  That way, one could edit the file using
>      'outline-move-subtree-{up,down}'.  That would have made this
>      reorganization quite a bit easier.

Adding a tag at the end of the same line would be a big improvement.

Re: Organizing the NEWS file a bit better

[Stefan Kangas]

Juri Linkov <juri@linkov.net> writes:

> > I tried hard to ensure nothing was lost,[1] but if you want to check
> > this yourself you could use, e.g.:
> >
> >     comm -3 <(git show HEAD^:etc/NEWS|sort) <(sort etc/NEWS)
>
> This shows that 'benchmark-call' is lost (I don't know if it needs a NEWS entry).

Thanks, now restored.

> Adding a tag at the end of the same line would be a big improvement.

Yes, it would certainly make editing the file easier, and help avoid
mishaps like the above.

Perhaps we could try it for Emacs 29?  If we do it soon after cutting
the new branch, it should be easier to change it back if we find any
reason to.

Re: Organizing the NEWS file a bit better

[Lars Ingebrigtsen]

Stefan Kangas <stefan@marxist.se> writes:

> Yes, it would certainly make editing the file easier, and help avoid
> mishaps like the above.
>
> Perhaps we could try it for Emacs 29?  If we do it soon after cutting
> the new branch, it should be easier to change it back if we find any
> reason to.

What would the lines look like?

** New user option 'use-short-answers'. :DOC:

and

** New user option 'use-short-answers'. :NODOC:

?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: Organizing the NEWS file a bit better

[Stefan Kangas]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> > Perhaps we could try it for Emacs 29?  If we do it soon after cutting
> > the new branch, it should be easier to change it back if we find any
> > reason to.
>
> What would the lines look like?
>
> ** New user option 'use-short-answers'. :DOC:
>
> and
>
> ** New user option 'use-short-answers'. :NODOC:
>
> ?

Yes.  The org format only requires a tag to be a) at the end of a
headline and b) enclosed in colons.

The command 'org-set-tags-command' lines them up like this, which
helps improve readability:

** 'open-gnutls-stream' now also accepts a ':coding' argument.          :DOC:
** 'process-attributes' now works under OpenBSD, too.                 :NODOC:

Re: Organizing the NEWS file a bit better

[Lars Ingebrigtsen]

Stefan Kangas <stefan@marxist.se> writes:

> The command 'org-set-tags-command' lines them up like this, which
> helps improve readability:
>
> ** 'open-gnutls-stream' now also accepts a ':coding' argument.          :DOC:
> ** 'process-attributes' now works under OpenBSD, too.                 :NODOC:

We try to limit the headings to below 80 characters...  which typically
means that a lot of them are almost exactly 80 characters.  :-)  So
these tags will make the NEWS file less readable.

The nice thing about having the tags on separate lines is that they
disappear from the VC history.  If we're changing the lines when we do
tagging, then it makes VC archaeology less convenient.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: Organizing the NEWS file a bit better

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Mon, 6 Sep 2021 04:30:56 +0200
> Cc: Emacs developers <emacs-devel@gnu.org>
> 
> Lars Ingebrigtsen <larsi@gnus.org> writes:
> 
> > > I'm looking at re-organizing NEWS a bit, and I'm not sure how we prefer it.
> > >
> > > In general, I guess I also wonder if anyone will protest if I take it
> > > upon myself to move things around to more sensible places.
> >
> > Please go ahead.
> 
> I have now pushed my reorganization of the NEWS file to master.

Thanks.  I made a few followup changes, but in general the result
LGTM.

Re: Organizing the NEWS file a bit better

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Mon, 6 Sep 2021 08:57:39 +0200
> Cc: Lars Ingebrigtsen <larsi@gnus.org>, Emacs developers <emacs-devel@gnu.org>
> > Adding a tag at the end of the same line would be a big improvement.
> 
> Yes, it would certainly make editing the file easier, and help avoid
> mishaps like the above.
> 
> Perhaps we could try it for Emacs 29?  If we do it soon after cutting
> the new branch, it should be easier to change it back if we find any
> reason to.

I don't understand what exactly is being proposed, can you show an
example?

In general, I dislike Org stuff that is left in the buffer (as opposed
to causing display of some reasonable faces or another visual cue).
For example, the #+begin_src..#+end_src markers are butt-ugly, IMO,
and should not be displayed in Org.  So if this is going to be
something similar, I wouldn't like it.  (Full disclosure: I do a lot
of changes in NEWS, all the time.)

I also don't really understand how the current markers are any worse
than something like "DOC:", can you explain?

Re: Organizing the NEWS file a bit better

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Mon, 6 Sep 2021 11:01:04 +0200
> Cc: Emacs developers <emacs-devel@gnu.org>, Juri Linkov <juri@linkov.net>
> 
> Lars Ingebrigtsen <larsi@gnus.org> writes:
> 
> > > Perhaps we could try it for Emacs 29?  If we do it soon after cutting
> > > the new branch, it should be easier to change it back if we find any
> > > reason to.
> >
> > What would the lines look like?
> >
> > ** New user option 'use-short-answers'. :DOC:
> >
> > and
> >
> > ** New user option 'use-short-answers'. :NODOC:
> >
> > ?
> 
> Yes.

Then PLEASE don't.  This makes the text much harder to read, even
before we consider lines that are long enough to overflow after this
addition.

What is the purpose? to make it easier to find entries that aren't
documented yet?  If so, why not use Occur or somesuch?

> The command 'org-set-tags-command' lines them up like this, which
> helps improve readability:
> 
> ** 'open-gnutls-stream' now also accepts a ':coding' argument.          :DOC:
> ** 'process-attributes' now works under OpenBSD, too.                 :NODOC:

IME, Org's tags are intended to be used with relatively short
headings, and these aren't.

Re: Organizing the NEWS file a bit better

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> What is the purpose? to make it easier to find entries that aren't
> documented yet?  If so, why not use Occur or somesuch?

Yeah, I just use Occur.

However, perhaps somebody should write a little major mode for NEWS that
handles the format a little better.  I.e., not autofilling the headings
along with the text, and make the outline commands understand the +++
stuff?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: Organizing the NEWS file a bit better

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Cc: Stefan Kangas <stefan@marxist.se>,  emacs-devel@gnu.org,  juri@linkov.net
> Date: Mon, 06 Sep 2021 13:07:39 +0200
> 
> However, perhaps somebody should write a little major mode for NEWS that
> handles the format a little better.  I.e., not autofilling the headings
> along with the text, and make the outline commands understand the +++
> stuff?

Sure, that'd be welcome, I think.

Re: Organizing the NEWS file a bit better

[Stefan Kangas]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> > ** 'open-gnutls-stream' now also accepts a ':coding' argument.          :DOC:
> > ** 'process-attributes' now works under OpenBSD, too.                 :NODOC:
>
> We try to limit the headings to below 80 characters...  which typically
> means that a lot of them are almost exactly 80 characters.  :-)  So
> these tags will make the NEWS file less readable.

We could allow headlines to be 80 characters excluding the tag.

> The nice thing about having the tags on separate lines is that they
> disappear from the VC history.  If we're changing the lines when we do
> tagging, then it makes VC archaeology less convenient.

AFAICT, VC archeology is already not very convenient after we cut the
release branch and move the file from etc/NEWS to etc/NEWS.28.  One
would need to visit the relevant release branch first.

(As a Magit user, walking backwards in "git blame" history for one
line that hasn't moved is just a matter of typing "b" one or more
times.  I have no idea how easy this is using vc, but I've assumed
it's harder since people are concerned about it.)

Re: Organizing the NEWS file a bit better

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Mon, 6 Sep 2021 20:17:52 +0200
> Cc: Emacs developers <emacs-devel@gnu.org>, Juri Linkov <juri@linkov.net>
> 
> AFAICT, VC archeology is already not very convenient after we cut the
> release branch and move the file from etc/NEWS to etc/NEWS.28.  One
> would need to visit the relevant release branch first.

I use VC archeology on NEWS all the time.  It is handy when I need to
know who and when added some new feature.

> (As a Magit user, walking backwards in "git blame" history for one
> line that hasn't moved is just a matter of typing "b" one or more
> times.  I have no idea how easy this is using vc, but I've assumed
> it's harder since people are concerned about it.)

Wrong tool, I think.  Try vc-region-history (I'm sure Magit has
something similar).  The relevant Git command is "git log -L".

Re: Organizing the NEWS file a bit better

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> > AFAICT, VC archeology is already not very convenient after we cut the
> > release branch and move the file from etc/NEWS to etc/NEWS.28.  One
> > would need to visit the relevant release branch first.
>
> I use VC archeology on NEWS all the time.  It is handy when I need to
> know who and when added some new feature.

In NEWS, I'm pretty sure that most of us do.

Lars' point was that it's nice that file history is preserved when the
markers are removed.  But those markers are only removed on the
release branch, in preparation of a release.  On master, the file is
moved to make way for a new NEWS file.  This breaks archeology
anyways.

(I hope we could improve this process so we don't have to move the
file.  This has been discussed elsewhere.)

> > (As a Magit user, walking backwards in "git blame" history for one
> > line that hasn't moved is just a matter of typing "b" one or more
> > times.  I have no idea how easy this is using vc, but I've assumed
> > it's harder since people are concerned about it.)
>
> Wrong tool, I think.  Try vc-region-history (I'm sure Magit has
> something similar).  The relevant Git command is "git log -L".

I've never used vc-region-history, but it is pretty neat.  If I
understand correctly, it breaks when lines are moved?

I think the better tool to use for archeology in NEWS, where lines are
frequently moved, is vc-annotate.  Using it, I can now see that it
allows me to trace changes backward in time (but it does involve more
typing and more new buffers than in Magit, and I remember now that
this is why I stopped using it).

Re: Organizing the NEWS file a bit better

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Mon, 6 Sep 2021 20:57:43 +0200
> Cc: Lars Ingebrigtsen <larsi@gnus.org>, Juri Linkov <juri@linkov.net>, 
> 	Emacs developers <emacs-devel@gnu.org>
> 
> > I use VC archeology on NEWS all the time.  It is handy when I need to
> > know who and when added some new feature.
> 
> In NEWS, I'm pretty sure that most of us do.
> 
> Lars' point was that it's nice that file history is preserved when the
> markers are removed.  But those markers are only removed on the
> release branch, in preparation of a release.  On master, the file is
> moved to make way for a new NEWS file.  This breaks archeology
> anyways.

It doesn't break it for me (though I don't think I understand what you
are describing: the archeology on the branch and on master are
separate and independent).

> I've never used vc-region-history, but it is pretty neat.  If I
> understand correctly, it breaks when lines are moved?

If they are moved far away, and if you didn't include that place in
the range, then yes, but you can always see where they were moved and
retry.

> I think the better tool to use for archeology in NEWS, where lines are
> frequently moved, is vc-annotate.

vc-region-history builds _upon_ annotate, and saves you the trouble of
invoking annotate many times, each time specifying the commit SHA.

Re: Organizing the NEWS file a bit better

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> It doesn't break it for me (though I don't think I understand what you
> are describing: the archeology on the branch and on master are
> separate and independent).

OK, so let's stick to master.  It's a known limitation in git that it
is hard to access after the file was moved.  Maybe I don't understand
what you're saying, but this limitation in git is exactly why we are
avoiding moving files in the first place.

Could you explain how you carry out archeology on etc/NEWS.27?  How do
I find out who introduced this line:

** Emacs now uses GMP, the GNU Multiple Precision library.

?

> vc-region-history builds _upon_ annotate, and saves you the trouble of
> invoking annotate many times, each time specifying the commit SHA.

I haven't ever had to specify a commit SHA with vc-annotate.

By the way, I realize I was being unfair to vc-annotate.  There are in
fact a number of commands that make going through history very
convenient, such as vc-annotate-next-revision,
vc-annotate-prev-revision, and vc-annotate-revision-at-line.

Re: Organizing the NEWS file a bit better

[Stefan Kangas]

Stefan Kangas <stefan@marxist.se> writes:

> OK, so let's stick to master.  It's a known limitation in git that it
> is hard to access after the file was moved.  Maybe I don't understand
             ^^^^^^ should be "access history"

> what you're saying, but this limitation in git is exactly why we are
> avoiding moving files in the first place.

Re: Organizing the NEWS file a bit better

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Mon, 6 Sep 2021 22:38:16 +0200
> Cc: Lars Ingebrigtsen <larsi@gnus.org>, Juri Linkov <juri@linkov.net>, 
> 	Emacs developers <emacs-devel@gnu.org>
> 
> Could you explain how you carry out archeology on etc/NEWS.27?  How do
> I find out who introduced this line:
> 
> ** Emacs now uses GMP, the GNU Multiple Precision library.
> 
> ?

I don't understand what this question has to do with the markers, can
you explain?

And NEWS.27 is only renamed once, after that we merge from the release
branch to it without renaming anything.  So again, I don't think I
understand why this is an issue.

Re: Organizing the NEWS file a bit better

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> > Could you explain how you carry out archeology on etc/NEWS.27?  How do
> > I find out who introduced this line:
> >
> > ** Emacs now uses GMP, the GNU Multiple Precision library.
> >
> > ?
>
> I don't understand what this question has to do with the markers, can
> you explain?

Lars claimed that markers are better for preserving history.  I
claimed that history is already lost at that point, so it is not very
important.

Re: Organizing the NEWS file a bit better

[Stefan Kangas]

Stefan Kangas <stefan@marxist.se> writes:

> Lars claimed that markers are better for preserving history.  I
                               ^ the markers we use today
> claimed that history is already lost at that point, so it is not very
> important.

Re: Organizing the NEWS file a bit better

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Tue, 7 Sep 2021 08:47:19 +0200
> Cc: Lars Ingebrigtsen <larsi@gnus.org>, Juri Linkov <juri@linkov.net>, 
> 	Emacs developers <emacs-devel@gnu.org>
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > > Could you explain how you carry out archeology on etc/NEWS.27?  How do
> > > I find out who introduced this line:
> > >
> > > ** Emacs now uses GMP, the GNU Multiple Precision library.
> > >
> > > ?
> >
> > I don't understand what this question has to do with the markers, can
> > you explain?
> 
> Lars claimed that markers are better for preserving history.  I
> claimed that history is already lost at that point, so it is not very
> important.

I understood what Lars said to mean that the current markers don't
affect any lines but their own.  Thus, their removal doesn't affect
any important stuff in the file.

And I don't agree that history is already lost when we remove the
markers.

Re: Organizing the NEWS file a bit better

[Lars Ingebrigtsen]

Stefan Kangas <stefan@marxist.se> writes:

> Lars' point was that it's nice that file history is preserved when the
> markers are removed.  But those markers are only removed on the
> release branch, in preparation of a release.  On master, the file is
> moved to make way for a new NEWS file.  This breaks archeology
> anyways.

That's true -- but we do go through the NEWS file to look for untagged
items and then tag them up.  So adding a :NODOC tag makes the
archaeology slightly more inconvenient from then on.  (I'm not saying
that this, in itself, is a deal breaker or anything, but it's just
another minor annoyance, that along with the other minor annoyances,
makes me less than enthusiastic about doing the tagging this way.)

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no