bug#74807: 30.0.90; Eglot: Non-Markdown strings rendered as Markdown

["João Távora" <joaotavora@gmail.com>]

Eli Zaretskii <eliz@gnu.org> writes:

> Ping!  Can we make some progress here, please?

>> [jsonrpc] e[08:23:09.518] --> textDocument/hover[13]
>> {"jsonrpc":"2.0","id":13,"method":"textDocument/hover","params":{"textDocument":{"uri":"file:///home/troy/junk/hello_world.gpr"},"position":{"line":4,"character":21}}}
>> [jsonrpc] e[08:23:09.531] <-- textDocument/hover[13]
>> {"jsonrpc":"2.0","id":13,"result":null}

Hello Troy,  I've finally had time to look at your bug report.

> I've run across a situation where Eglot receives a documentation
> string as part of a "completionItem/resolve".  The documentation is
> being provided as a regular "string", not MarkupContent, yet it is
> being rendered as markup.  Since the string contains characters which
> are being interpreted as markdown (e.g., ":"), it causes the
> documentation to be rendered incorrectly.

After perusing the spec, I'm not sure the simple strings cannot be
rendered as Markdown by the client.  The spec doesn't seem to
disambiguate this.  All it says about the documentation field of a
Completion structure, besides its polymorphic type, is that it is a

    /**
     * A human-readable string that represents a doc-comment.
     */
     documentation?: string | MarkupContent;


Anyway I think if the server wants to ensure something is _not_ rendered
as Markdown it should use the more advanced MarkupContent structure and
explicitly specify 'plaintext' in its MarkupKind field.

I understand this sounds counter-intuitive, but I have to be very
careful to do these kinds of changes.  As you know, Eglot works with a
large body of servers, and I wouldn't be at all surprised that some of
those servers (or, more importantly, regulat users of those servers) do
actually expect plain strings to be rendered as Markdown when such a
renderer is available.

Lastly, and adding to my reluctance to address this in code, I don't
understand what ':' is tripping the renderer here.  Last I checked, ':'
doesn't have any special meaning in Markdown, especially in the middle
of the sequence.  Emacs's `markdown-view-mode` from the markdown.el
package does give the left and right parts of:

   Indentation kind: spaces | tabs

a different face (I don't know why, the online renderers I've tried do
not do that).  But I wouldn't say it is being rendered "incorrectly".

Anyway, I lean strongly towards not touching this.
João