bug#51444: One issue in NEWS

bug#51444: One issue in NEWS

[Juri Linkov]

Currently I'm reading NEWS.28 and noticed this section marked by
+++ as documented in the manual:

  +++
  ** New user option 'next-error-message-highlight'.
  In addition to a fringe arrow, 'next-error' error may now optionally
  highlight the current error message in the 'next-error' buffer.
  This user option can be also customized to keep highlighting on all
  visited errors, so you can have an overview what errors were already visited.

But the source of the manual has only these two lines:

  @findex next-error-message
  @vindex next-error-message-highlight

'next-error-message' is a face and can be removed from the index.
But 'next-error-message-highlight' is a user option, and when
the reader selects it from the Info index, its page says nothing
about this option.  This patch fills the gap:

diff --git a/doc/emacs/building.texi b/doc/emacs/building.texi
index 8de93867ba..2c694a5e39 100644
--- a/doc/emacs/building.texi
+++ b/doc/emacs/building.texi
@@ -213,7 +213,6 @@ Compilation Mode
 @kindex M-g n
 @kindex C-x `
 @findex next-error
-@findex next-error-message
 @vindex next-error-message-highlight
 @vindex next-error-highlight
 @vindex next-error-highlight-no-select
@@ -263,7 +262,9 @@ Compilation Mode
 highlights the relevant source line.  The duration of this highlight
 is determined by the variable @code{next-error-highlight} for the locus
 in the selected buffer, and @code{next-error-highlight-no-select} for
-the locus in non-selected buffers.
+the locus in non-selected buffers.  Also you can customize the variable
+@code{next-error-message-highlight} that defines how to highlight the
+current error message in the buffer that contains messages.
 
 @vindex compilation-context-lines
   If the @file{*compilation*} buffer is shown in a window with a left
-- 

bug#51444: One issue in NEWS

[Eli Zaretskii]

> From: Juri Linkov <juri@linkov.net>
> Date: Wed, 27 Oct 2021 20:27:22 +0300
> 
> Currently I'm reading NEWS.28 and noticed this section marked by
> +++ as documented in the manual:
> 
>   +++
>   ** New user option 'next-error-message-highlight'.
>   In addition to a fringe arrow, 'next-error' error may now optionally
>   highlight the current error message in the 'next-error' buffer.
>   This user option can be also customized to keep highlighting on all
>   visited errors, so you can have an overview what errors were already visited.
> 
> But the source of the manual has only these two lines:
> 
>   @findex next-error-message
>   @vindex next-error-message-highlight
> 
> 'next-error-message' is a face and can be removed from the index.
> But 'next-error-message-highlight' is a user option, and when
> the reader selects it from the Info index, its page says nothing
> about this option.  This patch fills the gap:

Does that option need to be documented in the manual?  It sounds quite
obscure to me.

bug#51444: One issue in NEWS

[Juri Linkov]

>>   ** New user option 'next-error-message-highlight'.
>>   In addition to a fringe arrow, 'next-error' error may now optionally
>>   highlight the current error message in the 'next-error' buffer.
>>   This user option can be also customized to keep highlighting on all
>>   visited errors, so you can have an overview what errors were already visited.
>> 
>> But the source of the manual has only these two lines:
>> 
>>   @findex next-error-message
>>   @vindex next-error-message-highlight
>> 
>> 'next-error-message' is a face and can be removed from the index.
>> But 'next-error-message-highlight' is a user option, and when
>> the reader selects it from the Info index, its page says nothing
>> about this option.  This patch fills the gap:
>
> Does that option need to be documented in the manual?  It sounds quite
> obscure to me.

It's on a par with next-error-highlight and next-error-highlight-no-select:

- next-error-highlight and next-error-highlight-no-select are applied
  to the buffer visited by next-error;

- next-error-message-highlight highlighting is applied to the buffer
  with error messages and matches.

bug#51444: One issue in NEWS

[Eli Zaretskii]

> From: Juri Linkov <juri@linkov.net>
> Cc: 51444@debbugs.gnu.org
> Date: Wed, 27 Oct 2021 21:39:38 +0300
> 
> >>   @findex next-error-message
> >>   @vindex next-error-message-highlight
> >> 
> >> 'next-error-message' is a face and can be removed from the index.
> >> But 'next-error-message-highlight' is a user option, and when
> >> the reader selects it from the Info index, its page says nothing
> >> about this option.  This patch fills the gap:
> >
> > Does that option need to be documented in the manual?  It sounds quite
> > obscure to me.
> 
> It's on a par with next-error-highlight and next-error-highlight-no-select:
> 
> - next-error-highlight and next-error-highlight-no-select are applied
>   to the buffer visited by next-error;
> 
> - next-error-message-highlight highlighting is applied to the buffer
>   with error messages and matches.

So maybe none of them needs to be in the manual.

bug#51444: One issue in NEWS

[Juri Linkov]

>> > Does that option need to be documented in the manual?  It sounds quite
>> > obscure to me.
>>
>> It's on a par with next-error-highlight and next-error-highlight-no-select:
>>
>> - next-error-highlight and next-error-highlight-no-select are applied
>>   to the buffer visited by next-error;
>>
>> - next-error-message-highlight highlighting is applied to the buffer
>>   with error messages and matches.
>
> So maybe none of them needs to be in the manual.

I don't know 🤷

bug#51444: One issue in NEWS

[Juri Linkov]

close 51444 28.0.60
quit

>>> > Does that option need to be documented in the manual?  It sounds quite
>>> > obscure to me.
>>>
>>> It's on a par with next-error-highlight and next-error-highlight-no-select:
>>>
>>> - next-error-highlight and next-error-highlight-no-select are applied
>>>   to the buffer visited by next-error;
>>>
>>> - next-error-message-highlight highlighting is applied to the buffer
>>>   with error messages and matches.
>>
>> So maybe none of them needs to be in the manual.
>
> I don't know 🤷

I have no opinion whether they need to be in the manual,
so just fixed the problem of missing text for the existing vindex.

bug#51444: One issue in NEWS

[Juri Linkov]

>>> So maybe none of them needs to be in the manual.
>>
>> I don't know 🤷
>
> I have no opinion whether they need to be in the manual,
> so just fixed the problem of missing text for the existing vindex.

I noticed this entry has neither +++ nor --- indication in NEWS.28:

  *** The tab bar now supports more mouse commands.
  Clicking 'mouse-2' closes the tab, 'mouse-3' displays the context menu
  with items that operate on the clicked tab.  Dragging the tab with
  'mouse-1' moves it to another position on the tab bar.  Mouse wheel
  scrolling switches to the previous/next tab, and holding the Shift key
  during scrolling moves the tab to the left/right.

Should it be documented in the manual?

bug#51444: One issue in NEWS

[Lars Ingebrigtsen]

Juri Linkov <juri@linkov.net> writes:

> I noticed this entry has neither +++ nor --- indication in NEWS.28:
>
>   *** The tab bar now supports more mouse commands.
>   Clicking 'mouse-2' closes the tab, 'mouse-3' displays the context menu
>   with items that operate on the clicked tab.  Dragging the tab with
>   'mouse-1' moves it to another position on the tab bar.  Mouse wheel
>   scrolling switches to the previous/next tab, and holding the Shift key
>   during scrolling moves the tab to the left/right.
>
> Should it be documented in the manual?

The first few issues seem so self-evident that they don't need to be in
the manual.  But the mouse wheel and shift key thing perhaps should be?

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

bug#51444: One issue in NEWS

[Eli Zaretskii]

> From: Juri Linkov <juri@linkov.net>
> Cc: 51444@debbugs.gnu.org
> Date: Thu, 04 Nov 2021 19:36:29 +0200
> 
> I noticed this entry has neither +++ nor --- indication in NEWS.28:
> 
>   *** The tab bar now supports more mouse commands.
>   Clicking 'mouse-2' closes the tab, 'mouse-3' displays the context menu
>   with items that operate on the clicked tab.  Dragging the tab with
>   'mouse-1' moves it to another position on the tab bar.  Mouse wheel
>   scrolling switches to the previous/next tab, and holding the Shift key
>   during scrolling moves the tab to the left/right.
> 
> Should it be documented in the manual?

Yes, probably.

Thanks.

bug#51444: One issue in NEWS

[Juri Linkov]

>> I noticed this entry has neither +++ nor --- indication in NEWS.28:
>>
>>   *** The tab bar now supports more mouse commands.
>>   Clicking 'mouse-2' closes the tab, 'mouse-3' displays the context menu
>>   with items that operate on the clicked tab.  Dragging the tab with
>>   'mouse-1' moves it to another position on the tab bar.  Mouse wheel
>>   scrolling switches to the previous/next tab, and holding the Shift key
>>   during scrolling moves the tab to the left/right.
>>
>> Should it be documented in the manual?
>
> The first few issues seem so self-evident that they don't need to be in
> the manual.  But the mouse wheel and shift key thing perhaps should be?

I added the description as short as possible, without tables and indexes,
so maybe this is ok.