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

[Protesilaos Stavrou <info@protesilaos.com>]

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