bug#61072: How to change the length of the separation lines in eldoc, used by eglot?

bug#61072: How to change the length of the separation lines in eldoc, used by eglot?

[Wei-Ting Lin]

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

I prefer to have the information shown near the cursor, when it hovers on a
symbol. I use eldoc-doc for this purpose, and the result is like this
<https://i.imgur.com/8O0iEIJ.png>.

As seen in the screenshot, the line is too long for the child frame and
gets wrapped. How can I change the length of the line?

-------------------------------------------------------------------

This issue was posted in
https://github.com/joaotavora/eglot/discussions/1157 originally.

[-- Attachment #2: Type: text/html, Size: 687 bytes --]

bug#61072: How to change the length of the separation lines in eldoc, used by eglot?

[Ruijie Yu via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Wei-Ting Lin <linwaytin@gmail.com> writes:

> I prefer to have the information shown near the cursor, when it hovers on a symbol. I use eldoc-doc for this purpose, and the result is like this.

Can you attach the image as an attachment so that people without access
to imgur can see the screenshot?  Thanks.

Best,


RY

bug#61072: How to change the length of the separation lines in eldoc, used by eglot?

[Wei-Ting Lin]

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

Yes, here it is.

WT

On Thu, Jan 26, 2023 at 6:14 AM Ruijie Yu <ruijie@netyu.xyz> wrote:

>
> Wei-Ting Lin <linwaytin@gmail.com> writes:
>
> > I prefer to have the information shown near the cursor, when it hovers
> on a symbol. I use eldoc-doc for this purpose, and the result is like this.
>
> Can you attach the image as an attachment so that people without access
> to imgur can see the screenshot?  Thanks.
>
> Best,
>
>
> RY
>

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

[-- Attachment #2: eglot-with-eldoc-box.png --]
[-- Type: image/png, Size: 29043 bytes --]

bug#61072: How to change the length of the separation lines in eldoc, used by eglot?

[Felician Nemeth]

Wei-Ting Lin <linwaytin@gmail.com> writes:

> I prefer to have the information shown near the cursor, when it hovers on a
> symbol. I use eldoc-doc for this purpose, and the result is like this
> <https://i.imgur.com/8O0iEIJ.png>.
>
> As seen in the screenshot, the line is too long for the child frame and
> gets wrapped. How can I change the length of the line?

Can you show what did the LSP server send to Eglot?  The relevant
message should be near at the end of the events buffer, which you can
see by M-x eglot-events-buffer RET right after eldoc displays the
documentation.

Thanks.

> -------------------------------------------------------------------
>
> This issue was posted in
> https://github.com/joaotavora/eglot/discussions/1157 originally.

bug#61072: How to change the length of the separation lines in eldoc, used by eglot?

[Wei-Ting Lin]

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

Sorry for the late reply. I think the following is the relevant part, when
the cursor is on function "get_GF_cont_nonint".

[server-reply] (id:1144) Sat Feb 18 10:03:45 2023:
(:id 1144 :jsonrpc "2.0" :result
     (:contents
      (:kind "markdown" :value "### instance-method `get_GF_cont_nonint`
 \n\n---\n→ `double`  \nParameters:  \n- `double tau`\n- `const
std::vector<double> & new_tau`\n\n---\n```cpp\n// In AndersonModel\npublic:
double get_GF_cont_nonint(double tau, const std::vector<double>
&new_tau)\n```")
      :range
      (:end
       (:character 42 :line 166)
       :start
       (:character 24 :line 166))))
[server-reply] (id:1145) Sat Feb 18 10:03:46 2023:
(:id 1145 :jsonrpc "2.0" :result
     [(:kind 1 :range
             (:end
              (:character 42 :line 166)
              :start
              (:character 24 :line 166)))
      (:kind 1 :range
             (:end
              (:character 37 :line 185)
              :start
              (:character 19 :line 185)))])

Wei-Ting

On Thu, Feb 9, 2023 at 12:05 PM Felician Nemeth <felician.nemeth@gmail.com>
wrote:

> Wei-Ting Lin <linwaytin@gmail.com> writes:
>
> > I prefer to have the information shown near the cursor, when it hovers
> on a
> > symbol. I use eldoc-doc for this purpose, and the result is like this
> > <https://i.imgur.com/8O0iEIJ.png>.
> >
> > As seen in the screenshot, the line is too long for the child frame and
> > gets wrapped. How can I change the length of the line?
>
> Can you show what did the LSP server send to Eglot?  The relevant
> message should be near at the end of the events buffer, which you can
> see by M-x eglot-events-buffer RET right after eldoc displays the
> documentation.
>
> Thanks.
>
> > -------------------------------------------------------------------
> >
> > This issue was posted in
> > https://github.com/joaotavora/eglot/discussions/1157 originally.
>

[-- Attachment #2: Type: text/html, Size: 2801 bytes --]

bug#61072: How to change the length of the separation lines in eldoc, used by eglot?

[Felician Nemeth]

Wei-Ting Lin <linwaytin@gmail.com> writes:

> Sorry for the late reply. I think the following is the relevant part, when
> the cursor is on function "get_GF_cont_nonint".
>
> [server-reply] (id:1144) Sat Feb 18 10:03:45 2023:
> (:id 1144 :jsonrpc "2.0" :result
>      (:contents
>       (:kind "markdown" :value "### instance-method `get_GF_cont_nonint`
>  \n\n---\n→ `double`  \nParameters:  \n- `double tau`\n- `const
> std::vector<double> & new_tau`\n\n---\n```cpp\n// In AndersonModel\npublic:
> double get_GF_cont_nonint(double tau, const std::vector<double>
> &new_tau)\n```")

So the LSP server sends "---\n".  gfm-view-mode turns these three dashes
into a long separation line, which is then displayed by eldoc-box.
Neither gfm-view-mode nor eldoc-box is a part of Emacs or available from
GNU ELPA.  I'm therefore tempted to say that debbugs is not the right
place for this bug report.

However, when Eglot calls gfm-view-mode in eglot--format-markup the
window-width probably equals to the width of the window containing the
user's source code and eldoc-box seems to display the documentation in a
narrower window.  So maybe it would help if Eglot allowed the users to
run a custom function instead of calling gfm-view-mode in
eglot--format-markup.

bug#61072: How to change the length of the separation lines in eldoc, used by eglot?

[João Távora]

On Tue, Feb 21, 2023 at 5:11 PM Felician Nemeth
<felician.nemeth@gmail.com> wrote:

> So the LSP server sends "---\n".  gfm-view-mode turns these three dashes
> into a long separation line, which is then displayed by eldoc-box.
> Neither gfm-view-mode nor eldoc-box is a part of Emacs or available from
> GNU ELPA.  I'm therefore tempted to say that debbugs is not the right
> place for this bug report.
>
> However, when Eglot calls gfm-view-mode in eglot--format-markup the
> window-width probably equals to the width of the window containing the
> user's source code and eldoc-box seems to display the documentation in a
> narrower window.  So maybe it would help if Eglot allowed the users to
> run a custom function instead of calling gfm-view-mode in
> eglot--format-markup.

Yes, I see the problem.  Thanks for describing Felicián.

But I don't think your suggestion is the correct way to tackle it.

Rather,  Eglot should add a markdown-capable element to
eldoc-display-functions and hint in the documentation item
produced by Eglot's eldoc-documentation-functions that that item
has a markdown version (it may also have a plaintext version
alongside),  taken directly from the LSP source. The new function
would then render the item appropriately.

Then users and other modes such as eldoc-box can also add things to
eldoc-display functions, read the hints (if they support them)
and do whatever they think is more suitable with the rich/poor
documentation item.

This is in principle already fully supported by the ElDoc
infrastructure, but needs someone to experiment with it (and
potentially find limitations in ElDoc, which I can help plug).

João

bug#61072: How to change the length of the separation lines in eldoc, used by eglot?

[Felician Nemeth]

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

> Rather,  Eglot should add a markdown-capable element to
> eldoc-display-functions and hint in the documentation item
> produced by Eglot's eldoc-documentation-functions that that item
> has a markdown version (it may also have a plaintext version
> alongside),  taken directly from the LSP source. The new function
> would then render the item appropriately.

Maybe I overthink this, but I wonder if it would make sense to specify
an optional content-type argument instead of a markdown-capable element.
That way, eldoc could potentially handle raw html texts as well.
Additionally, this would support different markdown variants.  And I'm
sure gnus/eww already has some helper functions that eldoc could reuse.

References for the text/markdown content-type:
  https://www.rfc-editor.org/rfc/rfc7763
  https://www.rfc-editor.org/rfc/rfc7764#section-3

bug#61072: How to change the length of the separation lines in eldoc, used by eglot?

[João Távora]

Felician Nemeth <felician.nemeth@gmail.com> writes:

> João Távora <joaotavora@gmail.com> writes:
>
>> Rather,  Eglot should add a markdown-capable element to
>> eldoc-display-functions and hint in the documentation item
>> produced by Eglot's eldoc-documentation-functions that that item
>> has a markdown version (it may also have a plaintext version
>> alongside),  taken directly from the LSP source. The new function
>> would then render the item appropriately.
>
> Maybe I overthink this, but I wonder if it would make sense to specify
> an optional content-type argument instead of a markdown-capable element.
> That way, eldoc could potentially handle raw html texts as well.
> Additionally, this would support different markdown variants.  And I'm
> sure gnus/eww already has some helper functions that eldoc could reuse.
>
> References for the text/markdown content-type:
>   https://www.rfc-editor.org/rfc/rfc7763
>   https://www.rfc-editor.org/rfc/rfc7764#section-3

This could be reasonable.  I've pushed some commits to master addressing
Eldoc/Eglot problems.  The protocol between
eldoc-documentation-functions and eldoc-display-functions is enhanced,
and eldoc-display-in-doc-buffer is now more independent, which could
pave the way for this kind of thing.  See docstring of
eldoc-documentation-functions.

I stopped short of adding :content-type there.  There's not much point
in moving rendering from Eglot to ElDoc if the rendering is going to
suck just as bad.  So I think this has to be analyzed carefully.  Here
are some ideas:

1. Use eww to render HTML, as you suggest.  But how to get that HTML?
   Call an external process?

2. You seem to suggest that eww can render markdown directly.  Sure?

3. Lobby for markdown.el to become more render-friendly, (remove hard
   newlines from paragraphs, remove invisible text, etc.)

4. Make a new Markdown mode based on a tree-sitter grammar

João

bug#61072: How to change the length of the separation lines in eldoc, used by eglot?

[Felician Nemeth]

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

> See docstring of eldoc-documentation-functions.

The docstring is quite easy to follow.  Nice work.

> I stopped short of adding :content-type there.  There's not much point
> in moving rendering from Eglot to ElDoc if the rendering is going to
> suck just as bad.  So I think this has to be analyzed carefully.  Here
> are some ideas:
>
> 1. Use eww to render HTML, as you suggest.  But how to get that HTML?
>    Call an external process?

My idea was to leave the door open for a potential ElDoc backend that
produces raw HTML documentation.  But it is a half-backed idea.  I don't
know how images should be specified.  Just as an IMG tag: <img
src="example.jpg">.  Or inline like in an email.

If I understood correctly, one of your original ideas was to let ElDoc
backends (Eglot) to specify a flag whether the documentation was in
markdown format.  Using terminology of the
eldoc-documentation-functions, I simply suggested a :content-type key to
generalize the markdown flag hoping Emacs had helper functions to help
handling a content-type specification.

Unfortunately, I now see a small problem with the :content-type
approach.  How should Eglot know whether ElDoc can render a markdown
formatted documentation?  If Eglot can request the documentation in
multiple formats, how it should know which one to choose.

> 2. You seem to suggest that eww can render markdown directly.  Sure?

This is a misunderstanding.  I didn't intend to suggest that.

> 3. Lobby for markdown.el to become more render-friendly, (remove hard
>    newlines from paragraphs, remove invisible text, etc.)

Sure, but can a better markdown.el solve the original issue?  Is there a
way to render a separation line independently of the current
window-width?

> 4. Make a new Markdown mode based on a tree-sitter grammar

I think a simple mode just to view a markdown document would be useful.
However, tree-sitter only helps parse a document.  Turning an abstract
syntax tree into a viewable Emacs buffer is still a substantial work, I
suppose.

Felicián

bug#61072: How to change the length of the separation lines in eldoc, used by eglot?

[João Távora]

Felician Nemeth <felician.nemeth@gmail.com> writes:

> João Távora <joaotavora@gmail.com> writes:
>
>> See docstring of eldoc-documentation-functions.
>
> The docstring is quite easy to follow.  Nice work.
>
>> I stopped short of adding :content-type there.  There's not much point
>> in moving rendering from Eglot to ElDoc if the rendering is going to
>> suck just as bad.  So I think this has to be analyzed carefully.  Here
>> are some ideas:
>>
>> 1. Use eww to render HTML, as you suggest.  But how to get that HTML?
>>    Call an external process?
>
> My idea was to leave the door open for a potential ElDoc backend that
> produces raw HTML documentation.  But it is a half-backed idea.  I don't
> know how images should be specified.  Just as an IMG tag: <img
> src="example.jpg">.  Or inline like in an email.
>
> If I understood correctly, one of your original ideas was to let ElDoc
> backends (Eglot) to specify a flag whether the documentation was in
> markdown format.  Using terminology of the
> eldoc-documentation-functions, I simply suggested a :content-type key to
> generalize the markdown flag hoping Emacs had helper functions to help
> handling a content-type specification.

Yes, exactly.  I ended up not following up on my idea because we don't
have a very good markdown renderer yet, so it's not particularly useful
to introduce this indirection yet.  And this content-type idea of yours
seemed more generic, more ambitious, and generally better.

> Unfortunately, I now see a small problem with the :content-type
> approach.  How should Eglot know whether ElDoc can render a markdown
> formatted documentation?  If Eglot can request the documentation in
> multiple formats, how it should know which one to choose.

I was going to just have Eglot ask Eldoc: "do you support Markdown?" and
then report the corresponding capability to the server.

>> 3. Lobby for markdown.el to become more render-friendly, (remove hard
>>    newlines from paragraphs, remove invisible text, etc.)
>
> Sure, but can a better markdown.el solve the original issue?  Is there a
> way to render a separation line independently of the current
> window-width?

Yes, there is, with just the same code we use in eldoc now to separate
documentation from different backends.

   (concat "\n" (propertize "\n" 'face '(:inherit separator-line :extend
   t)) "\n")

I've mailed Jason Blevins, markdown.el maintainer but he hasn't
responded.  Maybe make a bug report in the Github repo.

But window-width independence doesn't end there.  A proper renderer
would probably remove hard new lines in markdown paragraphs, so that
text can be wrapped automatically to windows with visual-line-mode does.
Or another way to get the same effect.

>> 4. Make a new Markdown mode based on a tree-sitter grammar
>
> I think a simple mode just to view a markdown document would be useful.
> However, tree-sitter only helps parse a document.  Turning an abstract
> syntax tree into a viewable Emacs buffer is still a substantial work, I
> suppose.

You're right, but one has to start somewhere...  Or not.  Maybe a couple
of patches to markdown.el and a gfm-render-mode with no hard newlines in
paragraphs (presuming markdown.el knows where paragraphs live) is the
shortest path to victory?

João

bug#61072: How to change the length of the separation lines in eldoc, used by eglot?

[Felician Nemeth]

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

>> Sure, but can a better markdown.el solve the original issue?  Is there a
>> way to render a separation line independently of the current
>> window-width?
>
> Yes, there is, with just the same code we use in eldoc now to separate
> documentation from different backends.
>
>    (concat "\n" (propertize "\n" 'face '(:inherit separator-line :extend
>    t)) "\n")

Surprisingly, this does not work in the *scratch* buffer.  It does work
in a non elisp-mode buffer.  I wonder why.

make-separator-line is a bit more complicated than the code above.
Would it make sense to use that when it's available? (I.e., Emacs 29 and
above.)

> I've mailed Jason Blevins, markdown.el maintainer but he hasn't
> responded.  Maybe make a bug report in the Github repo.

Yuan Fu (CC'd) has already made one:
https://github.com/jrblevin/markdown-mode/issues/753

> But window-width independence doesn't end there.  A proper renderer
> would probably remove hard new lines in markdown paragraphs, so that
> text can be wrapped automatically to windows with visual-line-mode does.
> Or another way to get the same effect.

I'd say let's take baby steps.

Felicián

bug#61072: How to change the length of the separation lines in eldoc, used by eglot?

[Yuan Fu]

> On Mar 29, 2023, at 10:48 AM, Felician Nemeth <felician.nemeth@gmail.com> wrote:
> 
> João Távora <joaotavora@gmail.com> writes:
> 
>>> Sure, but can a better markdown.el solve the original issue?  Is there a
>>> way to render a separation line independently of the current
>>> window-width?
>> 
>> Yes, there is, with just the same code we use in eldoc now to separate
>> documentation from different backends.
>> 
>>   (concat "\n" (propertize "\n" 'face '(:inherit separator-line :extend
>>   t)) "\n")
> 
> Surprisingly, this does not work in the *scratch* buffer.  It does work
> in a non elisp-mode buffer.  I wonder why.

If font-lock-mode is on, it overwrites the ‘face property. I always apply both ‘face and ‘font-lock-face to be safe.

> 
> make-separator-line is a bit more complicated than the code above.
> Would it make sense to use that when it's available? (I.e., Emacs 29 and
> above.)
> 
>> I've mailed Jason Blevins, markdown.el maintainer but he hasn't
>> responded.  Maybe make a bug report in the Github repo.
> 
> Yuan Fu (CC'd) has already made one:
> https://github.com/jrblevin/markdown-mode/issues/753

The contributor thinks their fix for another problem also solves the issue I raised, but I don’t have the energy to argue with them.

Yuan

bug#61072: How to change the length of the separation lines in eldoc, used by eglot?

[Felician Nemeth]

>> https://github.com/jrblevin/markdown-mode/issues/753

As the underlying problem has been fixed in mardown-mode, can we close
this bug?

bug#61072: How to change the length of the separation lines in eldoc, used by eglot?

[João Távora]

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

Yes, I think so. Doing that now.

On Sat, Apr 8, 2023, 09:52 Felician Nemeth <felician.nemeth@gmail.com>
wrote:

> >> https://github.com/jrblevin/markdown-mode/issues/753
>
> As the underlying problem has been fixed in mardown-mode, can we close
> this bug?
>

[-- Attachment #2: Type: text/html, Size: 655 bytes --]

bug#61072: How to change the length of the separation lines in eldoc, used by eglot?

[João Távora]

Wei-Ting Lin <linwaytin@gmail.com> writes:

> As seen in the screenshot, the line is too long for the child frame and gets wrapped. How can I change the length of the
> line?

> This issue was posted in https://github.com/joaotavora/eglot/discussions/1157 originally. 

Hello,

I'm sorry for the long delay in replying to this.  I've investigated
this issue today.  This issue in on my radar with lots of other related
Eglot/ElDoc issues (see for example bug#62029)

I think this one specifically is coming from the markdown.el library
(https://jblevins.org/projects/markdown-mode/).  I'm copying in the
maintainer, Jason Blevins.

Jason, you're probably out of the loop.  Eglot is using gfm-view-mode to
"render" Markdown snippets in temporary buffers, so it can then shoot
that results as a propertized string to ElDoc, which shows it in
different outlets (buffers, echo area, child frames, etc.

The very long separator we're seeing in the screenshot is markdown.el's
way of rendering Markdown horizontal rulers.  There, it uses this code:

    (defun markdown-fontify-hrs (last)
      "Add text properties to horizontal rules from point to LAST."
      ...
                      `(display ,(make-string
                                  (1- (window-body-width)) hr-char)))))
      ...
          t)))

As we can see, `window-body-width' is used, which is problematic because
it creates text with a display spec which might not match the size of
the window used for showing this text.  Instead, markdown.el could use
something like propertizing that text witha special face, which doesn't
suffer from this shortcoming.  To see how it behaves, evaluate this code

  (with-current-buffer (pop-to-buffer "*test*")
    (insert "foo\n")
    (insert (propertize "\n" 'face '(:inherit separator-line :extend t)))
    (insert "bar\n")
    (insert (propertize "\n" 'face '(:inherit separator-line :extend t)))
    (insert "baz"))

While we're on the topic, there are other things that could make
markdown.el much more useful for ElDoc/Eglot's purposes, like being able
to "fill" paragraphs regions to specific lengths (maybe infinite
lengths, so that visual-line-mode can do its thing)

João