On Thu, Nov 10, 2022 at 11:23 AM Eli Zaretskii wrote: > > From: João Távora > > Date: Thu, 10 Nov 2022 10:15:41 +0000 > > Cc: emacs-devel > > > > Arash, I think your suggestion of recommending `with-eval-after-load` > > is pertinent and should be added to the manual. > > How about adding a command to add servers to the list instead? See > below. > > > Eli, even though we provide a healthy dose of built-in server invocations > > in that variable, we can't and shouldn't aim at being exhaustive. > > > > Eglot's manual is meant to be a go-to guide for knowing how to resolve > > simple problems such as this one, which is very common. The problems > > solved by eglot-workspace-configuration and other variables are also > > very common. The manual should be reasonably self sufficient, not too > > terse or relying on the user's knowledge. > > IMNSHO, it is not the mission of the Eglot manual to teach people > with-eval-after-load and in general how to update lists that aren't > autoloaded or preloaded. This is a slippery slope. > I understand your opinion, and I share it mostly. But this is not that slippery. We also have short mentions in passing of directory-local variables because they are essential to setting up eglot-workspace-configuration. Short mentions of Emacs's facilities and links to other documentation deepening those concepts is the best strategy. I've used it in the README.md and MANUAL.md that preceded this manual and I can attest that it worked well. If making the variable autoloaded can make use skip the with-eval-after-load, and has no other pitfalls, then I'm OK with that too. Whatever works and makes the manual self-sufficient in this very simple and common task. > That said, I have no objection to converting eglot-server-programs into > > a defcustom, if someone will commit to translating and maintaining all > > the complex combination of options into "widget" form. I don't have the > > time or inclination for this task, but maybe someone has. > > It is not a good idea to have a defcustom whose value should be such a > complex data structure. I agree, but a command is a not a solution IMO: this belongs in the user's configuration file. A good docstring (can it be improved?) containing good descriptions and some ready-made recipes is the current and best approach to these things.