ELPA: add lin.el

ELPA: add lin.el

[Protesilaos Stavrou]

[-- Attachment #1: Type: text/plain, Size: 1420 bytes --]

Hello everyone,

I have a small package called "LIN Is Noticeable" (LIN, lin, lin.el,
etc.).  It locally remaps the 'hl-line' face.

The user can enable 'lin-mode' in select major modes to have a more
intense (or just different) style for the highlighted line of
'hl-line-mode', without compromising the utility of the 'hl-line' face
in all other buffers.

Quote from the documentation:

    The idea is that 'hl-line' cannot work equally well for contexts
    with competing priorities: (i) line selection, or (ii) simple line
    highlight.  In the former case, the current line needs to be made
    prominent because it carries a specific meaning of some significance
    in the given context.  Whereas in the latter case, the primary mode
    of interaction does not revolve around the line highlight itself: it
    may be because the focus is on editing text or reading through the
    buffer's contents, so the current line highlight is more of a gentle
    reminder of the point's location on the vertical axis.

LIN does not enable 'hl-line-mode'.  It just remaps the 'hl-line' face.

I attach the patch for elpa.git.  What do you think?  I can provide
screenshots in case you need a demonstration.

Note that I received contributions from Nicolas De Jaeghere (in Cc).
Nicolas has also assigned copyright to the FSF.

All the best,
Protesilaos (or simply "Prot")

-- 
Protesilaos Stavrou
https://protesilaos.com

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-elpa-packages-lin-Add-package.patch --]
[-- Type: text/x-patch, Size: 846 bytes --]

From 1060655766e33788d9a6b849935c45484722c50d Mon Sep 17 00:00:00 2001
Message-Id: <1060655766e33788d9a6b849935c45484722c50d.1636138741.git.info@protesilaos.com>
From: Protesilaos Stavrou <info@protesilaos.com>
Date: Fri, 5 Nov 2021 20:58:37 +0200
Subject: [PATCH] * elpa-packages (lin): Add package

---
 elpa-packages | 1 +
 1 file changed, 1 insertion(+)

diff --git a/elpa-packages b/elpa-packages
index e26a428c25..42d72d6874 100644
--- a/elpa-packages
+++ b/elpa-packages
@@ -295,6 +295,7 @@
  ("leaf"		:url "https://github.com/conao3/leaf.el")
  ("let-alist"		:core "lisp/emacs-lisp/let-alist.el")
  ("lex"			:url nil)
+ ("lin" :url "https://gitlab.com/protesilaos/lin" :main-file "lin.el" :doc "README.org")
  ("lmc"			:url nil)
  ("load-dir"		:url nil)
  ("load-relative"	:url "https://github.com/rocky/emacs-load-relative")
-- 
2.33.1

Re: ELPA: add lin.el

[Stefan Kangas]

Hi Protesilaos,

Protesilaos Stavrou <info@protesilaos.com> writes:

> The user can enable 'lin-mode' in select major modes to have a more
> intense (or just different) style for the highlighted line of
> 'hl-line-mode', without compromising the utility of the 'hl-line' face
> in all other buffers.

This looks useful, thanks.  My question is: why make it into a
third-party package instead of a patch against hl-line.el?  I imagine
that we could introduce a new permanently local defvar that users (or
even mode developers?) could set in individual modes.  If that variable
is non-nil, these faces are used instead of the default ones.  We could
also have a defcustom that disables this completely (I think it should
be on by default, but we can bikeshed that later).

We could also just include the mode of course, if we think that's the
better interface.  I sort of like the variables, as that allows modes to
"register" themselves as interesting for this purpose, and the user to
completely disable the functionality if they don't like it by setting a
defcustom.  (Instead of all users having tons of mode-hooks in their
configuration for each and every little mode where this could make
sense.)

What do you think?

Best regards,
Stefan Kangas

Re: ELPA: add lin.el

[Protesilaos Stavrou]

On 2021-11-05, 13:28 -0700, Stefan Kangas <stefankangas@gmail.com> wrote:

> Protesilaos Stavrou <info@protesilaos.com> writes:
>
>> The user can enable 'lin-mode' in select major modes to have a more
>> intense (or just different) style for the highlighted line of
>> 'hl-line-mode', without compromising the utility of the 'hl-line' face
>> in all other buffers.
>
> This looks useful, thanks.  My question is: why make it into a
> third-party package instead of a patch against hl-line.el?

The package has the upside that it can be used right away.  Whereas
changes in Emacs 29 will have to be followed by changes to all relevant
downstream packages that need to style hl-line accordingly (I know of
Elfeed, Mu4e, Notmuch).

I suggest we do both: let the package exist and also patch hl-line.el.

> I imagine that we could introduce a new permanently local defvar that
> users (or even mode developers?) could set in individual modes.  If
> that variable is non-nil, these faces are used instead of the default
> ones.  We could also have a defcustom that disables this completely (I
> think it should be on by default, but we can bikeshed that later).
>
> We could also just include the mode of course, if we think that's the
> better interface.  I sort of like the variables, as that allows modes to
> "register" themselves as interesting for this purpose, and the user to
> completely disable the functionality if they don't like it by setting a
> defcustom.  (Instead of all users having tons of mode-hooks in their
> configuration for each and every little mode where this could make
> sense.)
>
> What do you think?

I think having major modes register themselves in that way is the best
outcome.  The presence of a separate minor-mode/package is just a way to
work around the current constraints.

-- 
Protesilaos Stavrou
https://protesilaos.com

Re: ELPA: add lin.el

[Stefan Kangas]

Protesilaos Stavrou <info@protesilaos.com> writes:

> The package has the upside that it can be used right away.

That's true.

> Whereas changes in Emacs 29 will have to be followed by changes to all
> relevant downstream packages that need to style hl-line accordingly (I
> know of Elfeed, Mu4e, Notmuch).

OTOH, major packages are not uncommonly quick to adapt to changes in
master, seeing as they have quite a few users tracking the master
branch.  But it is true that users not doing that would need to wait to
actually get the functionality.

> I suggest we do both: let the package exist and also patch hl-line.el.

Sounds good to me.

Re: ELPA: add lin.el

[Protesilaos Stavrou]

[-- Attachment #1: Type: text/plain, Size: 361 bytes --]

On 2021-11-05, 21:29 +0200, Protesilaos Stavrou <info@protesilaos.com> wrote:

> I have a small package called "LIN Is Noticeable" (LIN, lin, lin.el,
> etc.).  It locally remaps the 'hl-line' face.
>
> [...]

Just to note that I updated the patch to remove the unnecesary
':main-file'.  Please find it attached.

-- 
Protesilaos Stavrou
https://protesilaos.com

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-elpa-packages-lin-New-package.patch --]
[-- Type: text/x-patch, Size: 826 bytes --]

From 61b8e4309d97737417ad2059138b762d6fd670f1 Mon Sep 17 00:00:00 2001
Message-Id: <61b8e4309d97737417ad2059138b762d6fd670f1.1636486995.git.info@protesilaos.com>
From: Protesilaos Stavrou <info@protesilaos.com>
Date: Tue, 9 Nov 2021 21:43:03 +0200
Subject: [PATCH] * elpa-packages (lin): New package

---
 elpa-packages | 1 +
 1 file changed, 1 insertion(+)

diff --git a/elpa-packages b/elpa-packages
index 72254082bf..926ade78f0 100644
--- a/elpa-packages
+++ b/elpa-packages
@@ -295,6 +295,7 @@
  ("leaf"		:url "https://github.com/conao3/leaf.el")
  ("let-alist"		:core "lisp/emacs-lisp/let-alist.el")
  ("lex"			:url nil)
+ ("lin" :url "https://gitlab.com/protesilaos/lin" :doc "README.org")
  ("lmc"			:url nil)
  ("load-dir"		:url nil)
  ("load-relative"	:url "https://github.com/rocky/emacs-load-relative")
-- 
2.33.1

Re: ELPA: add lin.el

[Stefan Monnier]

Protesilaos Stavrou [2021-11-09 21:46:35] wrote:
> On 2021-11-05, 21:29 +0200, Protesilaos Stavrou <info@protesilaos.com> wrote:
>> I have a small package called "LIN Is Noticeable" (LIN, lin, lin.el,
>> etc.).  It locally remaps the 'hl-line' face.
>>
>> [...]
>
> Just to note that I updated the patch to remove the unnecesary
> ':main-file'.  Please find it attached.

I'm strongly in favor of turning this into a patch to `hl-line-mode` and
would prefer we do that quickly and skip having it as a separate package
in GNU ELPA.


        Stefan

Re: ELPA: add lin.el

[Protesilaos Stavrou]

On 2021-11-09, 15:15 -0500, Stefan Monnier <monnier@iro.umontreal.ca> wrote:

> Protesilaos Stavrou [2021-11-09 21:46:35] wrote:
>> On 2021-11-05, 21:29 +0200, Protesilaos Stavrou <info@protesilaos.com> wrote:
>>> I have a small package called "LIN Is Noticeable" (LIN, lin, lin.el,
>>> etc.).  It locally remaps the 'hl-line' face.
>>>
>>> [...]
>>
>> Just to note that I updated the patch to remove the unnecesary
>> ':main-file'.  Please find it attached.
>
> I'm strongly in favor of turning this into a patch to `hl-line-mode` and
> would prefer we do that quickly and skip having it as a separate package
> in GNU ELPA.

Fine.  Stefan Kangas also suggests updating hl-line-mode (in another
reply to this thread).  I will look into it and prepare a patch.

I just thought I would publish a standalone package as it can be used on
Emacs 27.

-- 
Protesilaos Stavrou
https://protesilaos.com

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

[Protesilaos Stavrou]

[-- Attachment #1: Type: text/plain, Size: 796 bytes --]

On 2021-11-09, 15:15 -0500, Stefan Monnier <monnier@iro.umontreal.ca> wrote:

> Protesilaos Stavrou [2021-11-09 21:46:35] wrote:
>> On 2021-11-05, 21:29 +0200, Protesilaos Stavrou <info@protesilaos.com> wrote:
>>> I have a small package called "LIN Is Noticeable" (LIN, lin, lin.el,
>>> etc.).  It locally remaps the 'hl-line' face.
>>>
>>> [...]
>>
>> Just to note that I updated the patch to remove the unnecesary
>> ':main-file'.  Please find it attached.
>
> I'm strongly in favor of turning this into a patch to `hl-line-mode` and
> would prefer we do that quickly and skip having it as a separate package
> in GNU ELPA.

Following your advice, I have prepared a patch for hl-line.el.  Please
find it attached.  Feel welcome to make changes.

-- 
Protesilaos Stavrou
https://protesilaos.com

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Make-hl-line-mode-use-semantic-line-highlighting.patch --]
[-- Type: text/x-patch, Size: 5144 bytes --]

From 4a102722170673a23f80cab7e552bc8696a9c935 Mon Sep 17 00:00:00 2001
Message-Id: <4a102722170673a23f80cab7e552bc8696a9c935.1636553396.git.info@protesilaos.com>
From: Protesilaos Stavrou <info@protesilaos.com>
Date: Wed, 10 Nov 2021 16:08:42 +0200
Subject: [PATCH] Make hl-line-mode use semantic line highlighting

* etc/NEWS: Document the new face, user option, buffer-local variable,
and underlying rationale.

* lisp/hl-line.el (hl-line-selection): New face for selection-based
user interfaces.
(hl-line-selection-ui): User option to toggle the feature.
(hl-line-select-line-style): Buffer-local variable intended for
major modes to register themselves as relevant for the purposes of
selection-based interactivity.
(hl-line--face): Helper function to select the appropriate face.
(hl-line-make-overlay): Use helper function.
---
 etc/NEWS        | 20 ++++++++++++++++++++
 lisp/hl-line.el | 46 +++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 65 insertions(+), 1 deletion(-)

diff --git a/etc/NEWS b/etc/NEWS
index 97da145bc3..624f4c6f5a 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -94,6 +94,26 @@ These will take you (respectively) to the next and previous "page".
 ---
 *** 'describe-char' now also outputs the name of emoji combinations.
 
+** 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.
+
 ** Outline Minor Mode
 
 +++
diff --git a/lisp/hl-line.el b/lisp/hl-line.el
index 26cfcc3f9c..2eca090376 100644
--- a/lisp/hl-line.el
+++ b/lisp/hl-line.el
@@ -79,6 +79,17 @@ (defface hl-line
   :version "22.1"
   :group 'hl-line)
 
+(defface hl-line-selection
+  '((default :extend t)
+    (((class color) (min-colors 88) (background light))
+     :background "#b0d8ff")
+    (((class color) (min-colors 88) (background dark))
+     :background "#103265")
+    (t :inherit hl-line))
+  "Like `hl-line' face, but intended to indicate a selection UI."
+  :version "29.1"
+  :group 'lin)
+
 (defcustom hl-line-face 'hl-line
   "Face with which to highlight the current line in Hl-Line mode."
   :type 'face
@@ -92,6 +103,22 @@ (defcustom hl-line-face 'hl-line
 	 (when (overlayp global-hl-line-overlay)
 	   (overlay-put global-hl-line-overlay 'face hl-line-face))))
 
+(defcustom hl-line-selection-ui t
+  "When non-nil, apply `hl-line-selection' face if possible.
+That face is used in major modes that opt-in to supporting the
+semantics of a selection-based user interface, instead of the
+standard line highlight which may be treated as a means of
+identifying the point in the buffer.
+
+Major modes register themselves for this feature by setting the
+buffer-local variable `hl-line-select-line-style' to non-nil.
+
+When this option is set to nil, the HL-Line mode always applies
+the `hl-line-face'."
+  :type 'boolean
+  :version "29.1"
+  :group 'hl-line)
+
 (defcustom hl-line-sticky-flag t
   "Non-nil means the HL-Line mode highlight appears in all windows.
 Otherwise Hl-Line mode will highlight only in the selected
@@ -128,6 +155,17 @@ (defvar hl-line-overlay-buffer nil
 (defvar hl-line-overlay-priority -50
   "Priority used on the overlay used by hl-line.")
 
+(defvar-local hl-line-select-line-style nil
+  "When non-nil use `hl-line-selection' instead of `hl-line' face.
+This variable is meant to be set to non-nil in major modes where
+the line highlight denotes selecting the current entry, rather
+than merely highlighting where the cursor is.
+
+Users/themes can thus differentiate between the faces `hl-line'
+and `hl-line-selection' based on their semantics: the former may
+be set to a more subtle style, the latter to a more prominent
+one.")
+
 ;;;###autoload
 (define-minor-mode hl-line-mode
   "Toggle highlighting of the current line (Hl-Line mode).
@@ -153,10 +191,16 @@ (define-minor-mode hl-line-mode
     (hl-line-unhighlight)
     (remove-hook 'change-major-mode-hook #'hl-line-unhighlight t)))
 
+(defun hl-line--face ()
+  "Use appropriate face for line highlight."
+  (if (and hl-line-select-line-style hl-line-selection-ui)
+      'hl-line-selection
+    hl-line-face))
+
 (defun hl-line-make-overlay ()
   (let ((ol (make-overlay (point) (point))))
     (overlay-put ol 'priority hl-line-overlay-priority) ;(bug#16192)
-    (overlay-put ol 'face hl-line-face)
+    (overlay-put ol 'face (hl-line--face))
     ol))
 
 (defun hl-line-highlight ()
-- 
2.33.1

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

[Eli Zaretskii]

> 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?

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

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

>> +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.
[snip]
> Could you please rework the documentation so that it becomes more
> user-facing?

I'd propose two entries, and put one of them under "Lisp changes" to
describe what major modes need to do to use this new functionality by
default.

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

[Protesilaos Stavrou]

[-- Attachment #1: Type: text/plain, Size: 1807 bytes --]

On 2021-11-10, 16:33 +0200, Eli Zaretskii <eliz@gnu.org> wrote:

>> 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.
>
> [... 22 lines elided]
>
> 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?

Thank you Eli for the feedback!  I have tried to clarify the language
and avoid the term "selection", opting instead for "line-oriented user
interfaces".

Patch attached.

On 2021-11-10, 06:53 -0800, Stefan Kangas <stefankangas@gmail.com> wrote:

> Eli Zaretskii <eliz@gnu.org> writes:
>
>>> +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.
> [snip]
>> Could you please rework the documentation so that it becomes more
>> user-facing?
>
> I'd propose two entries, and put one of them under "Lisp changes" to
> describe what major modes need to do to use this new functionality by
> default.

Thank you Stefan!  I followed your advice in documenting those.

-- 
Protesilaos Stavrou
https://protesilaos.com

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Add-line-oriented-style-for-hl-line-mode.patch --]
[-- Type: text/x-patch, Size: 6342 bytes --]

From f90cfd709ccbad13bccc1a262e54220fd79c88ee Mon Sep 17 00:00:00 2001
Message-Id: <f90cfd709ccbad13bccc1a262e54220fd79c88ee.1636562815.git.info@protesilaos.com>
From: Protesilaos Stavrou <info@protesilaos.com>
Date: Wed, 10 Nov 2021 18:46:48 +0200
Subject: [PATCH] Add line-oriented style for hl-line-mode

* etc/NEWS: Document new user option and how major modes can support it.

* lisp/hl-line.el (hl-line-line-oriented): New face for highlighting
in line-oriented user interfaces.
(hl-line-use-line-oriented-ui): New user option to toggle
line-oriented highlighting in supporting major modes.
(hl-line-line-oriented-ui): Add local variable intended for use by
major modes.
(hl-line--face): Include helper function to use the appropriate face.
(hl-line-make-overlay): Use the new helper function.
---
 etc/NEWS        | 34 +++++++++++++++++++++++++++++++++
 lisp/hl-line.el | 51 ++++++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 84 insertions(+), 1 deletion(-)

diff --git a/etc/NEWS b/etc/NEWS
index 97da145bc3..c0920ade71 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -94,6 +94,31 @@ These will take you (respectively) to the next and previous "page".
 ---
 *** 'describe-char' now also outputs the name of emoji combinations.
 
+** hl-line-mode
+
+---
+*** Apply semantics of line-oriented line highlighting
+The user option 'hl-line-use-line-oriented-ui' controls the
+application of the new 'hl-line-line-oriented' face.
+
+That face is used in major modes that opt-in to supporting the
+semantics of a line-oriented user interface.  Those are UIs where only
+the current line matters, regardless of the horizontal position of
+point.  For example, when viewing a list of buffers, the default
+action is to visit the one on the current line, no matter where
+exactly the cursor is on that line.  Whereas non-line-oriented UIs,
+such as those where text editing is the main type of interaction, do
+consider the position of the point on the current line.
+
+The distinction between these two types of line highlighting allows
+users/themes to apply different styles to the applicable faces, each
+optimized for its context: the standard 'hl-line' may become more
+subtle, while the 'hl-line-line-oriented' ought to be more prominent.
+
+When this option is set to nil, the 'hl-line-mode' does not
+differentiate between the two types of line highlighting: it always
+applies the 'hl-line-face'.
+
 ** Outline Minor Mode
 
 +++
@@ -658,6 +683,15 @@ This holds the value of the previous call to 'set-locale-environment'.
 This macro can be used to change the locale temporarily while
 executing code.
 
+** hl-line-mode
+
+---
+*** Major modes can register support for line-oriented hl-line
+Set the buffer-local variable 'hl-line-line-oriented-ui' to non-nil.
+Doing so declares that the interface is line-oriented for the purposes
+of 'hl-line-mode', as explained elsewhere in this document or in the
+user option 'hl-line-use-line-oriented-ui'.
+
 ** Tabulated List Mode
 
 +++
diff --git a/lisp/hl-line.el b/lisp/hl-line.el
index 26cfcc3f9c..8044ce3ca0 100644
--- a/lisp/hl-line.el
+++ b/lisp/hl-line.el
@@ -79,6 +79,19 @@ (defface hl-line
   :version "22.1"
   :group 'hl-line)
 
+(defface hl-line-line-oriented
+  '((default :extend t)
+    (((class color) (min-colors 88) (background light))
+     :background "#b0d8ff")
+    (((class color) (min-colors 88) (background dark))
+     :background "#103265")
+    (t :inherit hl-line))
+  "Like `hl-line', but intended for line-oriented interfaces.
+Only applies when the user option `hl-line-use-line-oriented-ui'
+is non-nil and the major mode has registered to use this face."
+  :version "29.1"
+  :group 'lin)
+
 (defcustom hl-line-face 'hl-line
   "Face with which to highlight the current line in Hl-Line mode."
   :type 'face
@@ -92,6 +105,32 @@ (defcustom hl-line-face 'hl-line
 	 (when (overlayp global-hl-line-overlay)
 	   (overlay-put global-hl-line-overlay 'face hl-line-face))))
 
+(defcustom hl-line-use-line-oriented-ui t
+  "When non-nil, apply `hl-line-line-oriented' face if applicable.
+
+That face is used in major modes that opt-in to supporting the
+semantics of a line-oriented user interface.  Those are UIs where
+only the current line matters, regardless of the horizontal
+position of point.  For example, when viewing a list of buffers,
+the default action is to visit the one on the current line, no
+matter where exactly the cursor is on that line.  Whereas
+non-line-oriented UIs, such as those where text editing is the
+main type of interaction, do consider the position of the point
+on the current line.
+
+The distinction between these two types of line highlighting
+allows users/themes to apply different styles to the applicable
+faces, each optimized for its context: the standard `hl-line' may
+become more subtle, while the `hl-line-line-oriented' ought to be
+more prominent.
+
+When this option is set to nil, the HL-Line mode does not
+differentiate between the two types of line highlighting: it
+always applies the `hl-line-face'."
+  :type 'boolean
+  :version "29.1"
+  :group 'hl-line)
+
 (defcustom hl-line-sticky-flag t
   "Non-nil means the HL-Line mode highlight appears in all windows.
 Otherwise Hl-Line mode will highlight only in the selected
@@ -128,6 +167,10 @@ (defvar hl-line-overlay-buffer nil
 (defvar hl-line-overlay-priority -50
   "Priority used on the overlay used by hl-line.")
 
+(defvar-local hl-line-line-oriented-ui nil
+  "When non-nil use `hl-line-line-oriented' instead of `hl-line' face.
+The rationale is explained in `hl-line-use-line-oriented-ui'.")
+
 ;;;###autoload
 (define-minor-mode hl-line-mode
   "Toggle highlighting of the current line (Hl-Line mode).
@@ -153,10 +196,16 @@ (define-minor-mode hl-line-mode
     (hl-line-unhighlight)
     (remove-hook 'change-major-mode-hook #'hl-line-unhighlight t)))
 
+(defun hl-line--face ()
+  "Use appropriate face for line highlight."
+  (if (and hl-line-line-oriented-ui hl-line-use-line-oriented-ui)
+      'hl-line-line-oriented
+    hl-line-face))
+
 (defun hl-line-make-overlay ()
   (let ((ol (make-overlay (point) (point))))
     (overlay-put ol 'priority hl-line-overlay-priority) ;(bug#16192)
-    (overlay-put ol 'face hl-line-face)
+    (overlay-put ol 'face (hl-line--face))
     ol))
 
 (defun hl-line-highlight ()
-- 
2.33.1

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

[Eli Zaretskii]

> From: Protesilaos Stavrou <info@protesilaos.com>
> Cc: monnier@iro.umontreal.ca, emacs-devel@gnu.org
> Date: Wed, 10 Nov 2021 18:53:30 +0200
> 
> +The distinction between these two types of line highlighting allows
> +users/themes to apply different styles to the applicable faces, each
> +optimized for its context: the standard 'hl-line' may become more
> +subtle, while the 'hl-line-line-oriented' ought to be more prominent.

It sounds like the last part (after the colon) is the important part,
and is the reason for having a separate face.  So I wonder whether the
documentation could be made more up-to-a-point by stating this right
from the beginning.  Then I think you will be able to omit a large
part of the rest, because the above makes the reason very clear.

Thanks.