Subject: Re: bug#38778: 26.3; next-error-highlight set to t doesn't seem semi-permanent

From: Eli Zaretskii <[email-masked]>
Date: Tue, 03 Mar 2020 19:18:58 +0200

> From: Juri Linkov <[email-masked]>
> Date: Tue, 03 Mar 2020 00:03:10 +0200
> Cc: [email-masked]
> 
> Before closing this bug report, I propose to improve the documentation:

Thanks, please push to the release branch, after taking care of a nit
below.

>    When Emacs visits the locus of an error message, it momentarily
>  highlights the relevant source line.  The duration of this highlight
> -is determined by the variable @code{next-error-highlight}.
> +is determined by the variable @code{next-error-highlight} for
> +loci in selected buffers, and @code{next-error-highlight-no-select} for
        ^^^^^^^^^^^^^^^^^^^
There's only one selected buffer, so I'd suggest to say "in the
selected buffer", singular.

>  (defcustom next-error-highlight 0.5
>    "Highlighting of locations in selected source buffers.
> +See `next-error-highlight-no-select' to customize highlighting
> +of locations in non-selected buffers.
>  If a number, highlight the locus in `next-error' face for the given time
>  in seconds, or until the next command is executed.
>  If t, highlight the locus until the next command is executed, or until
> @@ -91,7 +93,9 @@ next-error-highlight
>    :version "22.1")
>  
>  (defcustom next-error-highlight-no-select 0.5
> -  "Highlighting of locations in `next-error-no-select'.
> +  "Highlighting of locations in non-selected source buffers.
> +Usually non-selected buffers are displayed by `next-error-no-select'.
> +See `next-error-highlight' to customize highlighting of selected buffers.
>  If number, highlight the locus in `next-error' face for given time in seconds.
>  If t, highlight the locus indefinitely until some other locus replaces it.
>  If nil, don't highlight the locus in the source buffer.

In these two doc strings, please move the reference to the other
variable to the end of the doc string.  That is the usual place for
"see also" kinds of text, because that way it doesn't disrupt the
reading of the documentation of this variable.