Re: Semantic hl-line-mode (was: ELPA: add lin.el)

[Eli Zaretskii <eliz@gnu.org>]

> From: Protesilaos Stavrou <info@protesilaos.com>
> Date: Wed, 10 Nov 2021 16:14:33 +0200
> Cc: emacs-devel <emacs-devel@gnu.org>
> 
> Following your advice, I have prepared a patch for hl-line.el.  Please
> find it attached.  Feel welcome to make changes.

Thanks.

> +** Semantic hl-line-mode
> +It is now possible to differentiate between two types of highlighting:
> +(i) line selection, or (ii) simple line highlight.  The former is
> +appropriate for interfaces that operate on the current line (e.g. a
> +listing of email threads), while the latter helps identify the point
> +on the vertical axis.
> +
> +Major modes can register themselves as having a selection-based
> +interface by setting the local variable 'hl-line-select-line-style' to
> +non-nil.  In that case, they will use the new 'hl-line-selection'
> +face.
> +
> +The user option 'hl-line-selection-ui' can be set to nil to disable
> +this feature altogether, meaning that only the 'hl-line-face' will be
> +applied.
> +
> +Users or theme developers may, in turn, choose to make the 'hl-line'
> +face more subtle while allowing a more prominent style where it is
> +really needed via the 'hl-line-selection' face.

I've read this text and the other documentation in the patch, and I
still don't understand what this does and how it differs from the
default operation of hl-line.  You describe quite a lot of
implementation-elated details, but very little information that can
help the user decide whether he or she wants this option.  I think one
problem (but not the only one) is that you use "selection", which is
an overloaded term (you definitely do NOT mean X selections, right?).

Could you please rework the documentation so that it becomes more
user-facing?