bug#47109: eldoc.el: Allow custom separator between documentations in the echo area

bug#47109: eldoc.el: Allow custom separator between documentations in the echo area

[Mathieu Marques]

[-- Attachment #1.1: Type: text/plain, Size: 916 bytes --]

Hello,

While trying out eglot.el, I played around with eldoc.el and needed to
display all pieces of documentations in the echo area at once. The joined
patch allows for a custom separator between said documentations.

First patch is a fix to indenting levels as well as untabifying the whole
file. That was done automatically by my configuration and given the
existing code I thought it would be beneficial to most to provide a patch
for that as well. Feel free to dismiss it if needed.

The second patch is the subject of this very email. With the updated code,
in the user configuration, one can customize the separator to `"\n"` and
its face to `((t :inherit shadow :strike-through t))` in order to have a
horizontal line between documentations in the echo area for instance.

I've tried following conventions described over at gnu.org, do let me know
if I've missed anything.

Best regards

-- 
Mathieu Marques

[-- Attachment #1.2: Type: text/html, Size: 1209 bytes --]

[-- Attachment #2: 0001-lisp-emacs-lisp-eldoc.el-Untabify-and-fix-indent-lev.patch --]
[-- Type: text/x-patch, Size: 5337 bytes --]

From 63d8a5f88d5a23cb2df215125e81ac78dd0d7e6a Mon Sep 17 00:00:00 2001
From: Mathieu Marques <mathieumarques78@gmail.com>
Date: Fri, 12 Mar 2021 19:43:10 +0100
Subject: [PATCH 1/2] * lisp/emacs-lisp/eldoc.el: Untabify and fix indent
 levels

---
 lisp/emacs-lisp/eldoc.el | 58 ++++++++++++++++++++--------------------
 1 file changed, 29 insertions(+), 29 deletions(-)

diff --git a/lisp/emacs-lisp/eldoc.el b/lisp/emacs-lisp/eldoc.el
index a02406a7b7..485ea26379 100644
--- a/lisp/emacs-lisp/eldoc.el
+++ b/lisp/emacs-lisp/eldoc.el
@@ -87,7 +87,7 @@ returns another string is acceptable.
 Note that this variable has no effect, unless
 `eldoc-documentation-strategy' handles it explicitly."
   :type '(radio (function-item upcase)
-		(function-item downcase)
+                (function-item downcase)
                 function))
 (make-obsolete-variable 'eldoc-argument-case nil "25.1")
 
@@ -183,12 +183,12 @@ It should receive the same arguments as `message'.")
 When `eldoc-print-after-edit' is non-nil, ElDoc messages are only
 printed after commands contained in this obarray."
   (let ((cmds (make-vector 31 0))
-	(re (regexp-opt '("delete" "insert" "edit" "electric" "newline"))))
+        (re (regexp-opt '("delete" "insert" "edit" "electric" "newline"))))
     (mapatoms (lambda (s)
-		(and (commandp s)
-		     (string-match-p re (symbol-name s))
-		     (intern (symbol-name s) cmds)))
-	      obarray)
+                (and (commandp s)
+                     (string-match-p re (symbol-name s))
+                     (intern (symbol-name s) cmds)))
+              obarray)
     cmds))
 
 \f
@@ -269,8 +269,8 @@ reflect the change."
            (memq eldoc-timer timer-idle-list)) ;FIXME: Why?
       (setq eldoc-timer
             (run-with-idle-timer
-	     eldoc-idle-delay nil
-	     (lambda ()
+             eldoc-idle-delay nil
+             (lambda ()
                (when (or eldoc-mode
                          (and global-eldoc-mode
                               (eldoc--supported-p)))
@@ -291,23 +291,23 @@ reflect the change."
 Otherwise work like `message'."
   (if (minibufferp)
       (progn
-	(add-hook 'minibuffer-exit-hook
-		  (lambda () (setq eldoc-mode-line-string nil
-			      ;; https://debbugs.gnu.org/16920
-			      eldoc-last-message nil))
-		  nil t)
-	(with-current-buffer
-	    (window-buffer
-	     (or (window-in-direction 'above (minibuffer-window))
-		 (minibuffer-selected-window)
-		 (get-largest-window)))
+        (add-hook 'minibuffer-exit-hook
+                  (lambda () (setq eldoc-mode-line-string nil
+                                   ;; https://debbugs.gnu.org/16920
+                                   eldoc-last-message nil))
+                  nil t)
+        (with-current-buffer
+            (window-buffer
+             (or (window-in-direction 'above (minibuffer-window))
+                 (minibuffer-selected-window)
+                 (get-largest-window)))
           (when (and mode-line-format
                      (not (and (listp mode-line-format)
                                (assq 'eldoc-mode-line-string mode-line-format))))
-	    (setq mode-line-format
-		  (list "" '(eldoc-mode-line-string
-			     (" " eldoc-mode-line-string " "))
-			mode-line-format)))
+            (setq mode-line-format
+                  (list "" '(eldoc-mode-line-string
+                             (" " eldoc-mode-line-string " "))
+                        mode-line-format)))
           (setq eldoc-mode-line-string
                 (when (stringp format-string)
                   (apply #'format-message format-string args)))
@@ -327,8 +327,8 @@ Also store it in `eldoc-last-message' and return that value."
     ;; Emacs way of preventing log messages.
     (let ((message-log-max nil))
       (cond (eldoc-last-message
-	     (funcall eldoc-message-function "%s" eldoc-last-message))
-	    (omessage (funcall eldoc-message-function nil)))))
+             (funcall eldoc-message-function "%s" eldoc-last-message))
+            (omessage (funcall eldoc-message-function nil)))))
   eldoc-last-message)
 
 (defun eldoc--message-command-p (command)
@@ -350,8 +350,8 @@ Also store it in `eldoc-last-message' and return that value."
   (and eldoc-last-message
        (not (minibufferp))      ;We don't use the echo area when in minibuffer.
        (if (and (eldoc-display-message-no-interference-p)
-		(eldoc--message-command-p this-command))
-	   (eldoc--message eldoc-last-message)
+                (eldoc--message-command-p this-command))
+           (eldoc--message eldoc-last-message)
          ;; No need to call eldoc--message since the echo area will be cleared
          ;; for us, but do note that the last-message will be gone.
          (setq eldoc-last-message nil))))
@@ -667,9 +667,9 @@ Meant as a value for `eldoc-documentation-strategy'."
        (progn
          (defcustom ,secondary ,value ,docstring ,@more)
          (define-obsolete-variable-alias ',main ',secondary "eldoc-1.1.0"))
-       (progn
-         (defcustom ,main ,value ,docstring  ,@more)
-         (defvaralias ',secondary ',main ,docstring))))
+     (progn
+       (defcustom ,main ,value ,docstring  ,@more)
+       (defvaralias ',secondary ',main ,docstring))))
 
 (eldoc--documentation-strategy-defcustom eldoc-documentation-strategy
     eldoc-documentation-function
-- 
2.30.1


[-- Attachment #3: 0002-lisp-emacs-lisp-eldoc.el-Allow-custom-separator.patch --]
[-- Type: text/x-patch, Size: 1746 bytes --]

From 184d5aa6e4d594b044a62e15b6eab084da0abb29 Mon Sep 17 00:00:00 2001
From: Mathieu Marques <mathieumarques78@gmail.com>
Date: Fri, 12 Mar 2021 19:45:18 +0100
Subject: [PATCH 2/2] * lisp/emacs-lisp/eldoc.el (eldoc--format-doc-buffer):
 Allow custom separator

---
 lisp/emacs-lisp/eldoc.el | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/lisp/emacs-lisp/eldoc.el b/lisp/emacs-lisp/eldoc.el
index 485ea26379..93cb6e7df5 100644
--- a/lisp/emacs-lisp/eldoc.el
+++ b/lisp/emacs-lisp/eldoc.el
@@ -129,6 +129,13 @@ window.  If the value is the symbol `maybe', then the echo area
 is only skipped if the documentation doesn't fit there."
   :type 'boolean)
 
+(defcustom eldoc-documentation-separator ""
+  "Separator to use between each documentation thing, when multiple."
+  :type 'string)
+
+(defface eldoc-documentation-separator '((t (:extend t :inherit shadow)))
+  "Face to use for the separator between documentation things.")
+
 (defface eldoc-highlight-function-argument
   '((t (:inherit bold)))
   "Face used for the argument at point in a function's argument list.
@@ -490,7 +497,11 @@ This holds the results of the last documentation request."
                         ": "
                         this-doc))
                  do (insert this-doc)
-                 when rest do (insert "\n")
+                 when rest
+                 do (insert (concat
+                             "\n"
+                             (propertize eldoc-documentation-separator
+                                         'face 'eldoc-documentation-separator)))
                  finally (goto-char (point-min)))
         ;; Rename the buffer, taking into account whether it was
         ;; hidden or not
-- 
2.30.1

bug#47109: eldoc.el: Allow custom separator between documentations in the echo area

[Basil L. Contovounesios]

severity 47109 wishlist
tags 47109 patch
quit

Mathieu Marques <mathieumarques78@gmail.com> writes:

> While trying out eglot.el, I played around with eldoc.el and needed to
> display all pieces of documentations in the echo area at once. The
> joined patch allows for a custom separator between said
> documentations.

Thanks, CCing João as an expert on both packages.

> First patch is a fix to indenting levels as well as untabifying the
> whole file. That was done automatically by my configuration and given
> the existing code I thought it would be beneficial to most to provide
> a patch for that as well. Feel free to dismiss it if needed.

Indeed, the Emacs convention is to only make whitespace/formatting
changes when already modifying that code for other purposes.

> Subject: [PATCH 2/2] * lisp/emacs-lisp/eldoc.el (eldoc--format-doc-buffer):
>  Allow custom separator

The log message should also mention the new symbols being added, e.g.:

  Make ElDoc separator customizable

  * lisp/emacs-lisp/eldoc.el (eldoc-documentation-separator):
  New user option (bug#47109).
  (eldoc-documentation-separator): New face.
  (eldoc--format-doc-buffer): Use them as a custom separator.

> +(defcustom eldoc-documentation-separator ""
> +  "Separator to use between each documentation thing, when multiple."
> +  :type 'string)
> +
> +(defface eldoc-documentation-separator '((t (:extend t :inherit shadow)))

According to (info "(elisp) Defining Faces"), this syntax is supported
for backward compatibility; nowadays the preferred format is:

  '((t :inherit shadow :extend t))

But: ElDoc supports Emacs ≥ 26.3, so use of the newer :extend attribute
has to be conditional on that, e.g.:

  `((t :inherit shadow ,@(and (>= emacs-major-version 27) '(:extend t))))

> +  "Face to use for the separator between documentation things.")

Both the defcustom and the defface also need a :version tag.

Thanks,

-- 
Basil

bug#47109: eldoc.el: Allow custom separator between documentations in the echo area

[Mathieu Marques]

[-- Attachment #1.1: Type: text/plain, Size: 2298 bytes --]

Thanks for the feedback. Joined a replacement for 2nd patch following the
suggested improvements.

On Fri, Mar 12, 2021 at 10:13 PM Basil L. Contovounesios <contovob@tcd.ie>
wrote:

> severity 47109 wishlist
> tags 47109 patch
> quit
>
> Mathieu Marques <mathieumarques78@gmail.com> writes:
>
> > While trying out eglot.el, I played around with eldoc.el and needed to
> > display all pieces of documentations in the echo area at once. The
> > joined patch allows for a custom separator between said
> > documentations.
>
> Thanks, CCing João as an expert on both packages.
>
> > First patch is a fix to indenting levels as well as untabifying the
> > whole file. That was done automatically by my configuration and given
> > the existing code I thought it would be beneficial to most to provide
> > a patch for that as well. Feel free to dismiss it if needed.
>
> Indeed, the Emacs convention is to only make whitespace/formatting
> changes when already modifying that code for other purposes.
>
> > Subject: [PATCH 2/2] * lisp/emacs-lisp/eldoc.el
> (eldoc--format-doc-buffer):
> >  Allow custom separator
>
> The log message should also mention the new symbols being added, e.g.:
>
>   Make ElDoc separator customizable
>
>   * lisp/emacs-lisp/eldoc.el (eldoc-documentation-separator):
>   New user option (bug#47109).
>   (eldoc-documentation-separator): New face.
>   (eldoc--format-doc-buffer): Use them as a custom separator.
>
> > +(defcustom eldoc-documentation-separator ""
> > +  "Separator to use between each documentation thing, when multiple."
> > +  :type 'string)
> > +
> > +(defface eldoc-documentation-separator '((t (:extend t :inherit
> shadow)))
>
> According to (info "(elisp) Defining Faces"), this syntax is supported
> for backward compatibility; nowadays the preferred format is:
>
>   '((t :inherit shadow :extend t))
>
> But: ElDoc supports Emacs ≥ 26.3, so use of the newer :extend attribute
> has to be conditional on that, e.g.:
>
>   `((t :inherit shadow ,@(and (>= emacs-major-version 27) '(:extend t))))
>
> > +  "Face to use for the separator between documentation things.")
>
> Both the defcustom and the defface also need a :version tag.
>
> Thanks,
>
> --
> Basil
>


-- 
Mathieu Marques

[-- Attachment #1.2: Type: text/html, Size: 2972 bytes --]

[-- Attachment #2: 0002-Make-ElDoc-separator-customizable.patch --]
[-- Type: text/x-patch, Size: 1978 bytes --]

From d5a1701a75d7068d51835aab2f15153b9b989199 Mon Sep 17 00:00:00 2001
From: Mathieu Marques <mathieumarques78@gmail.com>
Date: Fri, 12 Mar 2021 19:45:18 +0100
Subject: [PATCH] Make ElDoc separator customizable

  * lisp/emacs-lisp/eldoc.el (eldoc-documentation-separator):
  New user option (bug#47109).
  (eldoc-documentation-separator): New face.
  (eldoc--format-doc-buffer): Use them as a custom separator.
---
 lisp/emacs-lisp/eldoc.el | 16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)

diff --git a/lisp/emacs-lisp/eldoc.el b/lisp/emacs-lisp/eldoc.el
index 485ea26379..81fb205610 100644
--- a/lisp/emacs-lisp/eldoc.el
+++ b/lisp/emacs-lisp/eldoc.el
@@ -129,6 +129,16 @@ window.  If the value is the symbol `maybe', then the echo area
 is only skipped if the documentation doesn't fit there."
   :type 'boolean)
 
+(defcustom eldoc-documentation-separator ""
+  "Separator to use between each documentation thing, when multiple."
+  :type 'string
+  :version "28.1")
+
+(defface eldoc-documentation-separator
+  `((t :inherit shadow ,@(and (>= emacs-major-version 27) '(:extend t))))
+  "Face to use for the separator between documentation things."
+  :version "28.1")
+
 (defface eldoc-highlight-function-argument
   '((t (:inherit bold)))
   "Face used for the argument at point in a function's argument list.
@@ -490,7 +500,11 @@ This holds the results of the last documentation request."
                         ": "
                         this-doc))
                  do (insert this-doc)
-                 when rest do (insert "\n")
+                 when rest
+                 do (insert (concat
+                             "\n"
+                             (propertize eldoc-documentation-separator
+                                         'face 'eldoc-documentation-separator)))
                  finally (goto-char (point-min)))
         ;; Rename the buffer, taking into account whether it was
         ;; hidden or not
-- 
2.30.1

bug#47109: eldoc.el: Allow custom separator between documentations in the echo area

[Basil L. Contovounesios]

Mathieu Marques <mathieumarques78@gmail.com> writes:

> Thanks for the feedback. Joined a replacement for 2nd patch following
> the suggested improvements.

LGTM, thanks,

-- 
Basil

bug#47109: eldoc.el: Allow custom separator between documentations in the echo area

[João Távora]

Thank you both,

Personally, I'm fine with the first whitespace patch, as long as it's
only whitespace.

I've had a look at the simple second patch and while such a thing is
indeed mostly innocuous (and potentially very useful), I wonder if we
shouldn't be a bit more ambitious.

There are bound to be many more sophisticated strategies for composing
items of documentation and it doesn't make sense, to me, for Eldoc to
add two new user-visible endpoints to what is already a long,
ad-hoc-tailored list of legacy endpoints just for the relatively limited
technique of "composition by concatenation".

For example, in elisp-mode, one plan could be have the composition of
the multiple documentation items collected by the elisp eldoc backends
resultin a documentation buffer that looks very much like what you get
from describe-symbol or C-h o in form, function and content.  That
potentially needs a much more sophisticated composition strategy that is
specific to the elisp-mode major mode.

So I'd argue for a a new eldoc-render-documentation function.

That should give the user enough freedom to do these basic separators
but doesn't bloat the API with limited micro-switches (at least not yet,
we can add such things in the main eldoc.el eventually).

eldoc-render-documentation could be a generic function given:

- the items of documentation to render

- the target "canvas", which may be a buffer (the eldoc buffer), the echo
  area, or some other object (a tooltip? some user-defined documentation
  container?)

It should output things in a buffer, or maybe a string.

There seems be bit of an overlap here with `eldoc-display-functions',
but it is rather a healthy relation, in my view.  Those functions should
be more concerned with managing access and visibility of the target
canvas than actually rendering the text, which may be specific to a
major-mode and a potentially orthogonal task.

So each element in `eldoc-display-functions` should call
`eldoc-render-documentation` passing it suitable arguments to produce
the final text.

João

bug#47109: eldoc.el: Allow custom separator between documentations in the echo area

[Mathieu Marques]

[-- Attachment #1.1: Type: text/plain, Size: 1094 bytes --]

 Hello again,

Thanks for the feedback.  I agree with the will of allowing more freedom.

I joined a replacement patch with the different route that this is now
taking,
namely the removal of `eldoc--format-doc-buffer' in favor of
`eldoc-render-documentation'.  Is that closer to what you had in mind?

There's an issue however with the `-hr` format function that won't work with
terminal-based Emacs due to `:strike-through` apparently not supported
there.  I
was wondering whether a simple mention of that limitation in the docstring
would
be enough?  Terminal-based users would still be able to use the default
format
function.  Regarding the `:extend` keyword not being supported on 26, I
think
a better way than conditionally add it would be to provide a second `-hr`
formatting function that relies on something that is supported on 26 ie.
overlay.  Although I have little to no experience with overlays so I'm not
sure
what would be the preferred way of making a horizontal divider.
Furthermore, it
shouldn't break when the render function is used to return a string.
-- 
Mathieu Marques

[-- Attachment #1.2: Type: text/html, Size: 1314 bytes --]

[-- Attachment #2: 0002-Add-a-responsible-Eldoc-render-to-target-function.patch --]
[-- Type: text/x-patch, Size: 8473 bytes --]

From b1b251d27c6bdf765ed70a79dca7741e6effa99c Mon Sep 17 00:00:00 2001
From: Mathieu Marques <mathieumarques78@gmail.com>
Date: Fri, 12 Mar 2021 19:45:18 +0100
Subject: [PATCH] Add a responsible Eldoc render-to-target function

  * lisp/emacs-lisp/eldoc.el (eldoc-render-documentation):
  Replace eldoc--format-doc-buffer (bug#47109).
  (eldoc--format-doc-buffer): Removed.
  (eldoc-display-in-buffer): Use the new render function.
  (eldoc-display-in-echo-area): Use the new render function.
  (eldoc-documentation-format-function): New user option.
  (eldoc-documentation-format-concat): New format function.
  (eldoc-documentation-format-concat-hr): New format function.
---
 lisp/emacs-lisp/eldoc.el | 125 +++++++++++++++++++++++++--------------
 1 file changed, 81 insertions(+), 44 deletions(-)

diff --git a/lisp/emacs-lisp/eldoc.el b/lisp/emacs-lisp/eldoc.el
index 485ea26379..64c622039f 100644
--- a/lisp/emacs-lisp/eldoc.el
+++ b/lisp/emacs-lisp/eldoc.el
@@ -129,6 +129,19 @@ window.  If the value is the symbol `maybe', then the echo area
 is only skipped if the documentation doesn't fit there."
   :type 'boolean)
 
+(defcustom eldoc-documentation-format-function #'eldoc-documentation-format-concat
+  "Function used to format documentation in the *eldoc* buffer.
+
+- `eldoc-documentation-format-concat': concatenates documentations together
+  joining with a newline character'.
+
+- `eldoc-documentation-format-concat-hr': concatenates documentations together
+  joining with a horizontal rule."
+  :type '(radio (function-item eldoc-documentation-format-concat)
+                (function-item eldoc-documentation-format-concat-hr)
+                function)
+  :version "28.1")
+
 (defface eldoc-highlight-function-argument
   '((t (:inherit bold)))
   "Face used for the argument at point in a function's argument list.
@@ -466,44 +479,71 @@ This holds the results of the last documentation request."
                                              (buffer-name)))
     (display-buffer (current-buffer))))
 
-(defun eldoc--format-doc-buffer (docs)
-  "Ensure DOCS are displayed in an *eldoc* buffer."
-  (with-current-buffer (if (buffer-live-p eldoc--doc-buffer)
-                           eldoc--doc-buffer
-                         (setq eldoc--doc-buffer
-                               (get-buffer-create " *eldoc*")))
-    (unless (eq docs eldoc--doc-buffer-docs)
-      (setq-local eldoc--doc-buffer-docs docs)
-      (let ((inhibit-read-only t)
-            (things-reported-on))
-        (erase-buffer) (setq buffer-read-only t)
-        (local-set-key "q" 'quit-window)
-        (cl-loop for (docs . rest) on docs
-                 for (this-doc . plist) = docs
-                 for thing = (plist-get plist :thing)
-                 when thing do
-                 (cl-pushnew thing things-reported-on)
-                 (setq this-doc
-                       (concat
-                        (propertize (format "%s" thing)
-                                    'face (plist-get plist :face))
-                        ": "
-                        this-doc))
-                 do (insert this-doc)
-                 when rest do (insert "\n")
-                 finally (goto-char (point-min)))
-        ;; Rename the buffer, taking into account whether it was
-        ;; hidden or not
-        (rename-buffer (format "%s*eldoc%s*"
-                               (if (string-match "^ " (buffer-name)) " " "")
-                               (if things-reported-on
-                                   (format " for %s"
-                                           (mapconcat
-                                            (lambda (s) (format "%s" s))
-                                            things-reported-on
-                                            ", "))
-                                 ""))))))
-  eldoc--doc-buffer)
+(defun eldoc-documentation-format-concat (items &optional separator)
+  "Return documentation ITEMS concatenated.
+Join with SEPARATOR which defaults to \n.
+See `eldoc-documentation-format-function'."
+  (mapconcat (lambda (item)
+               (pcase-let* ((`(,documentation . ,plist) item)
+                            (face (plist-get plist :face))
+                            (thing (plist-get plist :thing)))
+                 (concat (when thing
+                           (concat (propertize (format "%s" thing) 'face face) ": "))
+                         documentation)))
+             items
+             (or separator "\n")))
+
+(defun eldoc-documentation-format-concat-hr (items)
+  "Return ITEMS concatenated like `eldoc-documentation-format-concat' but join
+with a horizontal rule.
+See `eldoc-documentation-format-function'."
+  (let ((separator (concat
+                    "\n"
+                    (propertize "\n" 'face
+                                '(:extend t :inherit shadow :strike-through t)))))
+    (eldoc-documentation-format-concat items separator)))
+
+(defun eldoc--render-documentation-buffer (text buffer)
+  "Sub-routine to write documentation TEXT in BUFFER.  Return it afterwards."
+  (with-current-buffer buffer
+    (let ((inhibit-read-only t)
+          (things-reported-on))
+      (erase-buffer)
+      (setq-local buffer-read-only t)
+      (local-set-key "q" 'quit-window)
+      (insert text)
+      ;; Rename the buffer, taking into account whether it was hidden
+      (rename-buffer (format "%s*eldoc%s*"
+                             (if (string-match "^ " (buffer-name)) " " "")
+                             (if things-reported-on
+                                 (format " for %s"
+                                         (mapconcat
+                                          (lambda (s) (format "%s" s))
+                                          things-reported-on
+                                          ", "))
+                               "")))
+
+      ))
+  buffer)
+
+(defun eldoc-render-documentation (documentations &optional target)
+  "Render DOCUMENTATIONS onto TARGET.
+If optional TARGET is not provided, simply return the formatted string.  If it
+is t, render the documentation into the *eldoc* buffer `eldoc--doc-buffer'.
+Else, assume TARGET is a name that can be passed to `get-buffer-create'."
+  (unless (eq documentations eldoc--doc-buffer-docs)
+    (setq-local eldoc--doc-buffer-docs documentations)
+    (let ((buffer (when target
+                    (if (or (bufferp target) (stringp target))
+                        (get-buffer-create target)
+                      (setq eldoc--doc-buffer
+                            (get-buffer-create (if (buffer-live-p eldoc--doc-buffer)
+                                                   eldoc--doc-buffer
+                                                 " *eldoc*"))))))
+          (body (funcall eldoc-documentation-format-function documentations)))
+      (if buffer
+          (eldoc--render-documentation-buffer body buffer)
+        body))))
 
 (defun eldoc--echo-area-substring (available)
   "Given AVAILABLE lines, get buffer substring to display in echo area.
@@ -590,14 +630,11 @@ Honor `eldoc-echo-area-use-multiline-p' and
                ;; Else, given a positive number of logical lines, we
                ;; format the *eldoc* buffer, using as most of its
                ;; contents as we know will fit.
-               (with-current-buffer (eldoc--format-doc-buffer docs)
+               (with-current-buffer (eldoc-render-documentation docs t)
                  (save-excursion
                    (eldoc--echo-area-substring available))))
               (t ;; this is the "truncate brutally" situation
-               (let ((string
-                      (with-current-buffer (eldoc--format-doc-buffer docs)
-                        (buffer-substring (goto-char (point-min))
-                                          (line-end-position 1)))))
+               (let ((string (eldoc-render-documentation docs)))
                  (if (> (length string) width)  ; truncation to happen
                      (unless (eldoc--echo-area-prefer-doc-buffer-p t)
                        (truncate-string-to-width string width))
@@ -609,7 +646,7 @@ Honor `eldoc-echo-area-use-multiline-p' and
 (defun eldoc-display-in-buffer (docs interactive)
   "Display DOCS in a dedicated buffer.
 If INTERACTIVE is t, also display the buffer."
-  (eldoc--format-doc-buffer docs)
+  (eldoc-render-documentation docs t)
   (when interactive
     (eldoc-doc-buffer)))
 
-- 
2.30.1

bug#47109: eldoc.el: Allow custom separator between documentations in the echo area

[Lars Ingebrigtsen]

I have no comment on this patch, but I note that bug#44885 seems to deal
with similar issues (i.e., custom eldoc separators, if I skimmed that
bug report correctly).  

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

bug#47109: eldoc.el: Allow custom separator between documentations in the echo area

[João Távora]

Thanks for the ping, Lars.  I will read that bug, too.    I hope to
propose my own patch to solve this problem in the not so distant
future.

To be clear, I'm just slightly wary of introducing this patch, a limited
way to solve this, if that means we would have to provide backward
compatibility for it in case we want to move to a more robust system
later on. Thing is, as far as I understand it, between two Emacs
releases (i.e. in trunk) we're generally not obliged to provide this
backward compatibility.  But Eldoc is also distributed independently
in ELPA releases, directly from trunk, and that may change things
a bit.  So erring on the side of caution here.  Feel free to comment
on the policy followed here.

João

On Mon, May 17, 2021 at 4:38 PM Lars Ingebrigtsen <larsi@gnus.org> wrote:
>
> I have no comment on this patch, but I note that bug#44885 seems to deal
> with similar issues (i.e., custom eldoc separators, if I skimmed that
> bug report correctly).
>
> --
> (domestic pets only, the antidote for overdose, milk.)
>    bloggy blog: http://lars.ingebrigtsen.no
>


-- 
João Távora

bug#47109: eldoc.el: Allow custom separator between documentations in the echo area

[Lars Ingebrigtsen]

João Távora <joaotavora@gmail.com> writes:

> Thanks for the ping, Lars.  I will read that bug, too.    I hope to
> propose my own patch to solve this problem in the not so distant
> future.
>
> To be clear, I'm just slightly wary of introducing this patch, a limited
> way to solve this, if that means we would have to provide backward
> compatibility for it in case we want to move to a more robust system
> later on. Thing is, as far as I understand it, between two Emacs
> releases (i.e. in trunk) we're generally not obliged to provide this
> backward compatibility.  But Eldoc is also distributed independently
> in ELPA releases, directly from trunk, and that may change things
> a bit.  So erring on the side of caution here.  Feel free to comment
> on the policy followed here.

Yeah, I understand the worries here -- especially since eldoc is such a
central feature in Emacs.

So waiting while you develop a more thorough solution here is fine by me.

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