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

From: João Távora <[email-masked]>
Date: Tue, 28 Mar 2023 23:27:27 +0100

Felician Nemeth <[email-masked]> writes:

> João Távora <[email-masked]> 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