Re: [SPAM UNSURE] Explain a bit more on how to configure language server in Eglot's manual

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

Yuan Fu <casouri@gmail.com> writes:

>> On Mar 5, 2023, at 4:16 PM, João Távora <joaotavora@gmail.com> wrote:
>> 
>> Yuan, please show the patch to Eglot's manual and let's work from
>> there.
>
> I’m not an amazing writer, but here it is.

Thanks.  I think the most important part in your patch is to show me
exactly the points in the manual's writing that are confusing.

>> I'm also OK with adding more examples, and work on simplifying the
>> per-project configuration workflow, maybe by somehow making it
>> easier to translate that dotted path notation into the nested JSON
>> object that the server is ultimately looking for.
>
> I feel that explaining the relationship between the dotted notation,
> the JSON object and the plist value that eglot accepts is already some
> cognitive load. And adding a translator into the mix will make it
> worse. If we provide the translator but don’t explain how it works, it
> will be just as confusing. But I could be wrong, I didn’t ponder this
> too deeply.

The dotted-to-plist translator proposed is optional.  Some people
requested use of dotted notation and that will surely need a translator.
I wouldn't use it.

But you're right that it's orthogonal to the request of a clearly and
well-structured writing on this topic, which I agree that this version
of the manual doesn't offer (the old Eglot README was very slightly
better in this department, IIRC)

>> If this distinction is not clear in the manual, either, it should
>> be made so.
>
> initializatiOption is only mentioned in the documentation of
> eglot-server-progrems, while workspaceConfiguration has a dozen
> paragraphs devoted to it. So maybe it’s easy to take
> workspaceConfiguration as the “main” way to configure a server. 

No, there are two ways, and neither is more valuable than the other.  It
depends entirely on what the user wants.  

> Maybe we can spend a little bit of text noting initializationOption
> under the “Customizing eglot” section.

I'm leaning into making a dedicated "Server configuration" section with
3 subsections: initializationOptions, eglot-workspace-configuration, and
the representations of common JSON object that is used for both of them.

João