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

[Troy Brown <brownts@troybrown.dev>]

On Mon, Jan 6, 2025 at 7:28 PM João Távora <joaotavora@gmail.com> wrote:
>
> This VSCode argument is not meaningful to me.  Not only does it not
> command any special authority over disambiguation of an ambiguous spec,
> but the "regular users of those servers" I'm concerned with are longtime
> Eglot users, not VSCoders.

I think it's a good indication that if users of a language server
thought VSCode was behaving incorrectly, it would quickly be pointed
out and corrected.  Since the VSCode implementation stands as-is in
this area, it is an indication that users of language servers believe
that this is the correct behavior.  The fact is, VSCode gets a lot
more exposure than other LSP clients and should at least be used as a
data point.  I think it's unwise to completely disregard that
information.

> Those are the users I don't want to disturb.  Who's to say that Eglot users
> of your ada-language-server aren't quite happy to see "Indentation kind"
> fontified with a certain face  and "spaces | tabs" in another face?

I'm not quite sure what your point is.  I am both a user of Eglot and
a user of the language server and I'm not happy with this behavior,
nor do I think Eglot's behavior is correct.  How is my experience any
less important than any other user?  I am trying to point out where
the "Emacs experience" is subpar in an effort to correct those
undesirable behaviors and improve my Emacs user experience.

Moving on, I've done some digging and found historical information
that I believe is relevant.  Initially, the specification only
included "string" for the documentation field. (i.e., "documentation?:
 string;").  Then there was a Github issue logged proposing to support
markdown in the CompletionItem.documentation (see
https://github.com/microsoft/language-server-protocol/issues/111).
This is evidence that the original specification did not allow
markdown for strings in the "documentation" field.  The following is
the commit where the specification was updated to add MarkupContent as
an additional option, thus remaining backwards compatible for servers
who continue to specify non-markdown documentation as strings in
addition to allowing servers to provide markdown using (the new then)
MarkupContent:
   https://github.com/microsoft/language-server-protocol/commit/692c225dcb737e287e393f148d193877b0a2dd54