From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Michael Eliachevitch Newsgroups: gmane.emacs.devel Subject: Re: [PATCH] Explain a bit more on how to configure language server in Eglot's manual Date: Wed, 15 Mar 2023 11:49:12 +0000 Message-ID: <87sfe6dwil.fsf@posteo.de> References: <86sfeisu49.fsf@stephe-leake.org> <87356gvkkb.fsf@gmail.com> <87wn3jgof2.fsf@posteo.de> <878rfzt0h7.fsf@posteo.de> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="33984"; mail-complaints-to="usenet@ciao.gmane.io" To: =?utf-8?B?Sm/Do28gVMOhdm9yYQ==?= , emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Wed Mar 15 13:34:50 2023 Return-path: Envelope-to: ged-emacs-devel@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1pcQL4-0008L9-VY for ged-emacs-devel@m.gmane-mx.org; Wed, 15 Mar 2023 13:34:50 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1pcQKE-0006w4-RO; Wed, 15 Mar 2023 08:33:50 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1pcQKC-0006vo-IN for emacs-devel@gnu.org; Wed, 15 Mar 2023 08:33:48 -0400 Original-Received: from mout02.posteo.de ([185.67.36.66]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1pcQK6-0007Hm-BE for emacs-devel@gnu.org; Wed, 15 Mar 2023 08:33:48 -0400 Original-Received: from submission (posteo.de [185.67.36.169]) by mout02.posteo.de (Postfix) with ESMTPS id 89210240814 for ; Wed, 15 Mar 2023 13:33:40 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=posteo.de; s=2017; t=1678883620; bh=KLn8xtwjg9RUZX//PFzGqe30ijE/aVTFw+DcGVGv4n4=; h=From:To:Subject:Date:Autocrypt:OpenPGP:From; b=WUVJJOwGao5aWhtVWACKsCy7kpxyFnCw0MlRzk9v9Mlondvnshodh1ZrWrZ6ZKQH0 l2T6V0dxZtay+eVE5SzrLDemisXx5TKvNWXTV5HGaMnaaLMBVywDjlYP3dbKeQIaZM SjRv9CGikB2WEs56RXk+pcmcxIty4IFHp3kfDCHc4jej+177s1J4ZidQuRJSYslmRg 5UcKDzV12464VoDp4FAaumNBpJDMZKURvx+PAUMXXWIpWUor+O5d01yWbHFkLXdgI+ Isz2aK9OXs2va7gKJ5d2R77CVGcp6qwkYk95Pz6bFxNBnIz6gUNv/KwsfpQoDdeXTs r+mP4feyZ9AQQ== Original-Received: from customer (localhost [127.0.0.1]) by submission (posteo.de) with ESMTPSA id 4Pc8vR0PB6z9rxG; Wed, 15 Mar 2023 13:33:38 +0100 (CET) In-reply-to: <878rfzt0h7.fsf@posteo.de> Autocrypt: addr=m.eliachevitch@posteo.de; keydata=xsBNBFHFxZABCADAAv2siayhA7Etl85WcwcyMPBD2bt/6Wh3A8a12AURV5J4tprzgbdlxC0w1LofvklG7ls25NERAY931hvQW+f5GEI0pwoNNFXEkKDa8/J4SxhrqXx8CJA85owPq1g4cFeO1ooQJ32BewlRGsnhd+taYExZ76oaMnFtx6jYjf6mPbjDyiLhC+Og3MBpOqAnmX7mhStgJl0uru1ZGEB17tzzVuQ4ljDv/MvUagVFymQBhmlbzvze5eLeDn90Ot0DjWHy3HzCFMEnVqQy8rmEA8N9GOANwyMY79KVymsPakeNwacPRFzYXCZvolC5jtY6I/1ALvVtNc45JyZWty+rMPo3ABEBAAHNGG0uZWxpYWNoZXZpdGNoQHBvc3Rlby5kZcLAlAQTAQgAPhYhBFRpCMeCODrQ59iU7BuPlcgSXc4xBQJgUmWNAhsDBQkSToKgBQsJCAcCBhUKCQgLAgQWAgMBAh4BAheAAAoJEBuPlcgSXc4xqC8H/06lkI7BimgkSobuEzsD9LsIPEyz5uUaQAP77u1nfoO1vB0DEdPxn7f3H3Hs7nyUfPgvgsn+9rTSV+ubHH5f/bzgQZgES2WItbV7iM290j6nWSc/iCTLlTmM2KMNvbMB9xGzV0m+UjMyAa9zUhB/3N+rd5ya/oSiTKw2/UbgfM5fR1knIUgPDENlKjJvO7/71Sxwpc+gKvAR9lHRT8JzQMyFaFO+zbo53Z7FzDTuj7zVyQ4MPIhe+UMI4rtNZeyPDM0QTep0+N39JbDhvUVevOh 15XJTYXl2Zdhl/yunnOibtg3XKtToakc4FjWJGrw8njbges5YqaodeMq OpenPGP: url=https://posteo.de/keys/m.eliachevitch@posteo.de.asc Received-SPF: pass client-ip=185.67.36.66; envelope-from=m.eliachevitch@posteo.de; helo=mout02.posteo.de X-Spam_score_int: -43 X-Spam_score: -4.4 X-Spam_bar: ---- X-Spam_report: (-4.4 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, HTML_MESSAGE=0.001, RCVD_IN_DNSWL_MED=-2.3, RCVD_IN_MSPIKE_H2=-0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_HTML_ATTACH=0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.devel:304492 Archived-At: --=-=-= Content-Type: text/plain; format=flowed Some additional comments to my documentation patch for json arrays as lisp vectors from the previous mail: > I didn't rebuild the documentation yet but hope it will be fine. I rebuild it with `make doc' now and the changes I added look fine. I attached the HTML build. > and extend the existing advanced configuration :pylsp example with an array option I changed the example only for the "5.3 JSONRPC objects in Elisp" section. But you use the same plist twice in the "5.1.1 Examples" section. I didn't add the json array option in those two cases to keep the examples short. But one might argue in favour of keeping all plist examples consistent and also in favor of introducing vectors in the examples as early as possible. Not sure if that would be better, I thought it might be good to mention this. --=-=-= Content-Type: text/html; charset=utf-8 Content-Disposition: attachment; filename=eglot.html Content-Transfer-Encoding: quoted-printable Content-Description: HTML build of the eglot texinfo manual Eglot: The Emacs Client for the Language Server Protocol

Next: Quick Start=   [Contents][Index]

Eglot

Eglot is the Emacs client for the Language Server Prot= ocol (LSP). The name “Eglot” is an a= cronym that stands for “Emacs Polyglot&rdquo= ;. 1 Eglot p= rovides infrastructure and a set of commands for enriching the source code editing capabilities of Emacs via LSP. LSP is a standardized communications protocol between source code editors (such as Emacs) and language servers—programs external to Emacs which analyze the source code on behalf of Emacs. The protocol allows Emacs to receive various source code services from the server, such as description and location of function calls, types of variables, class definitions, syntactic errors, etc. This way, Emacs doesn’t need to implement the language-specific parsing and analysis capabilities in its own code, but is still capable of providing sophisticated editing features that rely on such capabilities, such as automatic code completion, go-to definition of function/class, documentation of symbol at-point, refactoring, on-the-fly diagnostics, and more.

Eglot itself is completely language-agnostic, but it can support any programming language for which there is a language server and an Emacs major mode.

This manual documents how to configure, use, and customize Eglot.

This manual is for Eglot, the Emacs LSP client.

Copyright © 2022–2023 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover Texts being “A GNU Manual&rd= quo;, and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled “GNU Free Documentation License&r= dquo;.

(a) The FSF’s Back-Cover Text is: “You have the freedom to c= opy and modify this GNU manual.”

Next: Eglot= and LSP Servers, Previous: Eglot, Up: Eglot &nb= sp; [Contents][Index]<= /p>

1 Quick Start

This chapter provides concise instructions for setting up and using Eglot with your programming project in common usage scenarios. For more detailed instructions regarding Eglot setup, see Eglot and LSP Servers. See Using Eglot, for detailed description of usi= ng Eglot, and see Customizing Eglot,= for adapting Eglot to less common use patterns.

Here’s how to start using Eglot with your programming project:

  1. Select and install a language server.

    Eglot comes pre-configured with many popular language servers, see the value of eglot-server-programs. If the server(= s) mentioned there satisfy your needs for the programming language(s) with which you want to use Eglot, you just need to make sure those servers are installed on your system. Alternatively, install one or more servers of your choice and add them to the value of eglot-server-programs, as described in Setting Up LSP Servers.

  2. Turn on Eglot for your project.

    To start using Eglot for a project, type M-x eglot RET in a buffer visiting any file that belongs to the project. This starts the language server configured for the programming language of that buffer, and causes Eglot to start managing all the files of the project which use the same programming language. The notion of a “project” used by Eglot is the same Emacs uses (see Projects in GNU Emacs Manual): in the simplest case, the “project” is the single file you are editing, but it can also be all the files in a single directory or a directory tree under some version control system, such as Git.

    Alternatively, you can start Eglot automatically from the major-mode hook of the mode used for the programming language; see Starting Eglot.

  3. Use Eglot.

    Most Eglot facilities are integrated into Emacs features, such as ElDoc, Flymake, Xref, and Imenu. However, Eglot also provides commands of its own, mainly to perform tasks by the LSP server, such as M-x eglot-rename (to rename an identifier acros= s the entire project), M-x eglot-format (to reformat and reinde= nt code), and some others. See Eglot Commands= , for the detailed list of Eglot commands.

  4. That’s it!

Next: Using Eglot= , Previous: Quick Sta= rt, Up: Eglot   [<= a href=3D"#SEC_Contents" title=3D"Table of contents" rel=3D"contents">Conte= nts][Index]

2 Eglot and LSP Server= s

This chapter describes how to set up Eglot for your needs, and how to start it.

Next: Starting Egl= ot, Up: E= glot and LSP Servers   [Contents][Index]

2.1 Setting Up LSP Se= rvers

For Eglot to be useful, it must first be combined with a suitable language server. Usually, that means running the server program locally as a child process of Emacs (see Pr= ocesses in GNU Emacs Lisp Reference Manual) and communicating with it via the standard input and output streams.

The language server program must be installed separately, and is not further discussed in this manual; refer to the documentation of the particular server(s) you want to install.

To use a language server, Eglot must know how to start it and which programming languages each server supports. This information is provided by the variable eglot-server-programs.

Variable: eglot-server-programs

This variable associates major modes with names and command-line arguments of the language server programs corresponding to the programming language of each major mode. It provides all the information that Eglot needs to know about the programming language of the source you are editing.

The value of the variable is an alist, whose elements are of the form (major-mode . server).

The major-mode of the alist elements can be eit= her a symbol of an Emacs major mode or a list of the form (mode :language-id id), with mode being a major-mode symbol and id a string that identifies the language to th= e server (if Eglot cannot by itself convert the major-mode to the language identifier string required by the server). In addition, major-mode can be a list of several major modes sp= ecified in one of the above forms – this means a running instance of the associated server is responsible for files of multiple major modes or languages in the project.

The server part of the alist elements can be on= e of the following:

(program args…)

This says to invoke program with zero or mo= re arguments args; the program is expected to communicate with = Emacs via the standard input and standard output streams.

(program args… :initializationOptions options…)

program is invoked with = args but options specifies how to construct the ‘:initializationOptions’ JSON object to pass the server on during the LSP handshake (see Advanced server configuration).

(host = port args…)

Here host is a string and port is a positive integer specifying a TCP connection to a remote server. The arg= s are passed to open-network-stream, e.g. if the conn= ection needs to use encryption or other non-default parameters (see Network in GNU Emacs Lisp Reference Manu= al).

(program args… :autoport moreargs…)<= /code>

program is started with a command line cons= tructed from args followed by an available server port and the = rest of arguments in moreargs; Eglot then establishes a TC= P connection with the server via that port on the local host.

function

This should be a function of a single argument: non-nil if the connection was requested interactively (e.g., by the e= glot command), otherwise nil. The function should r= eturn a value of any of the forms described above. This allows interaction with the user for determining the program to start and its command-line arguments.

Eglot comes with a fairly complete set of associations of major-modes to popular language servers predefined. If you need to add server associations to the default list, use add-to-list. For example, if there is a hypothetical language server program fools for the language = Foo which is supported by an Emacs major-mode foo-mode, you can add it to th= e alist like this: 

(with-eval-after-load 'eglot
  (add-to-list 'eglot-server-programs
               '(foo-mode . ("fools" "--stdio"))))

This will invoke the program fools with t= he command-line argument --stdio in support of editing source= files for which Emacs turns on foo-mode, and will communicate w= ith the program via the standard streams. As usual with invoking programs, the executable file fools should be in one of the d= irectories mentioned by the exec-path variable (see Subprocess Creation in GNU Emacs Lisp Reference Manual= ), for Eglot to be able to find it.

Sometimes, multiple servers are acceptable alternatives for handling a given major-mode. In those cases, you may combine the helper function eglot-alternatives with the functional form of eglot-server-programs. 

(with-eval-after-load 'eglot
  (add-to-list 'eglot-server-programs
               `(foo-mode . ,(eglot-alternatives
                               '(("fools" "--stdio")
                                 ("phewls" "--fast"))))=
))

If you have fools and phewls installed, the function produced by eglot-alternatives will pr= ompt for the server to use in foo-mode buffers. Else it wil= l use whichever is available.

Next: S= hutting Down LSP Servers, Previous: Setting Up LSP Servers, Up: Eglot and LSP Servers =   [Contents][Index]

2.2 Starting Eglot

The most common way to start Eglot is to simply visit a source file of a given language and use the command M-x eglot. T= his starts the language server suitable for the visited file’s major-mode, and attempts to connect to it. If the connection to the language server is successful, you will see the [eglot:project] indicator on the mode line which reflects the server that was started. If the server program couldn’t be started or connection to it failed, you will see an error message; in that case, try to troubleshoot the problem as described in Tr= oubleshooting Eglot. Once a language server was successfully started and Eglot connected to it, you can immediately start using the Emacs features supported by Eglot, as described in Eglot Features.

A single Eglot session for a certain major-mode usually serves all the buffers under that mode which visit files from the same project, so you don’t need to invoke M-x eglot again whe= n you visit another file from the same project which is edited using the same major-mode. This is because Eglot uses the Emacs project infrastructure, as described in Buffers, Projects= , and Eglot, and this knows about files that belong to the same project. Thus, after starting an Eglot session for some buffer, that session is automatically reused when visiting files in the same project with the same major-mode.

Alternatively, you could configure Eglot to start automatically for one or more major-modes from the respective mode hooks. Here’s an example for a hypothetical foo-mode: 

 (add-hook 'foo-mode-hook 'eglot-ensure)

The function eglot-ensure will start an Eglo= t session for each buffer in which foo-mode is turned on, if there= isn’t already an Eglot session that handles the buffer. Note that this variant of starting an Eglot session is non-interactive, so it should be used only when you are confident that Eglot can be started reliably for any file which may be visited with the major-mode in question.

When Eglot connects to a language server for the first time in an Emacs session, it runs the hook eglot-connect-hook (see Eglot Variables).

Previous: Starting= Eglot, Up: Eglot and LSP Servers   [Contents][Index]

2.3 Shutting Down = LSP Servers

When Eglot is turned on, it arranges for turning itself off automatically if the language server process terminates. Turning off Eglot means that it shuts down the server connection, ceases its management of all the buffers that use the server connection which was terminated, deactivates its minor mode, and restores the original values of the Emacs variables that Eglot changed when it was turned on. See Buffers, Projects, a= nd Eglot, for more details of what Eglot management of a buffer entails.

You can also shut down a language server manually, by using the command M-x eglot-shutdown. This prompts for the = server (unless there’s only one connection and it’s used in the current buffer= ), and then shuts it down. By default, it also kills the server’s events buffer (see Troubleshoot= ing Eglot), but a prefix argument prevents that.

Alternatively, you can customize the variable eglot-autoshutdown to a non-nil value, in which case Eglot will automatically shut down the language server process when the last buffer served by that language server is killed. The default of this variable is nil, so that visiting anoth= er file would automatically activate Eglot even when the project which started Eglot with the server no longer has any buffer associated with it. This default allows you to start a server only once in each Emacs session.

Next: Customizi= ng Eglot, Previous: Eglot and LSP Servers, Up: Eglot   [Contents][Index]

3 Using Eglot

This chapter describes in detail the features that Eglot provides and how it does that. It also provides reference sections for Eglot commands and variables.

Next: Buffers, = Projects, and Eglot, Up: Using Eglot   [Contents][Index]

3.1 Eglot Features

Once Eglot is enabled in a buffer, it uses LSP and the language-server capabilities to activate, enable, and enhance modern IDE features in Emacs. The features themselves are usually provided via other Emacs packages. Here’s the list of the main features that Eglot enables and provides:

  • At-point documentation: when point is at or near a symbol or an identifier, the information about the symbol/identifier, such as the signature of a function or class method and server-generated diagnostics, is made available via the ElDoc package (see Lisp Doc in GNU Emacs Manual). This allows majo= r modes to provide extensive help and documentation about the program identifiers.
  • On-the-fly diagnostic annotations with server-suggested fixes, via= the Flymake package (see G= NU Flymake manual). This improves and enhances the Flymake diagnostics, replacing the other Flymake backends.
  • Finding definitions and uses of identifiers, via Xref (see Xref in GNU Emacs Manual). Eglot provides a backend for the Xref capabilities which uses the language-server understanding of the program source. In particular, it eliminates the need to generate tags tables (see Tags tables in GNU Emacs Manual) for languages which are only supported by the etags= backend.
  • Buffer navigation by name of function, class, method, etc., via Im= enu (see Imenu in GNU Emac= s Manual). Eglot provides its own variant of imenu-create-index-function, which g= enerates the index for the buffer based on language-server program source analysis.
  • Enhanced completion of symbol at point by the completion-at-point command (see Symbol Completion in GNU= Emacs Manual). This uses the language-server’s parser data f= or the completion candidates.
  • Automatic reformatting of source code as you type it. This is sim= ilar to what the eglot-format command does (see belo= w), but is activated automatically as you type.
  • If a completion package such as company-mode<= /code>, a popular third-party completion package (or any other completion package), is installed, Eglot enhances it by providing completion candidates based on the language-server analysis of the source code. (company-mode can be installed from GNU ELPA.)
  • If yasnippet, a popular third-party pa= ckage for automatic insertion of code templates (snippets), is installed, and the language server supports snippet completion candidates, Eglot arranges for the completion package to instantiate these snippets using yasnippet. (yasnippet can be installed from GNU ELPA.)
  • If the popular third-party package markdown-m= ode is installed, and the server provides at-point documentation formatted as Markdown in addition to plain text, Eglot arranges for the ElDoc package to enrich this text with fontifications and other nice formatting before displaying it to the user. This makes the documentation shown by ElDoc look nicer on display.
  • In addition to enabling and enhancing other features and packages, Eglot also provides a small number of user commands based directly on the capabilities of language servers. These commands are:
    M-x eglot-rename

    This prompts for a new name for the symbol at point, and then modifi= es all the project source files to rename the symbol to the new name, based on editing data received from the language-server. See Buffers, Projects, and Eglot, for the = details of how project files are defined.

    M-x eglot-format

    This reformats and prettifies the current active region according to source formatting rules of the language-server. If the region is not active, it reformats the entire buffer instead.

    M-x eglot-format-buffer

    This reformats and prettifies the current buffer according to source formatting rules of the language-server.

    M-x eglot-code-actions
    M-x eglot-code-action-organize-imports
    M-x eglot-code-action-quickfix
    M-x eglot-code-action-extract
    M-x eglot-code-action-inline
    M-x eglot-code-action-rewrite

    These command allow you to invoke the so-called co= de actions: requests for the language-server to provide editing commands for various code fixes, typically either to fix an error diagnostic or to beautify/refactor code. For example, eglot-code-action-organize-imports rearranges t= he program imports—declarations of modules whose capabili= ties the program uses. These commands affect all the files that belong to the project. The command M-x eglot-code-actions will = pop up a menu of code applicable actions at point.

  • M-x eglot-inlay-hints-mode This command toggles LSP “inlay hints” on and off for the curre= nt buffer. Inlay hints are small text annotations to specific parts of the whole buffer, not unlike diagnostics, but designed to help readability instead of indicating problems. For example, a C++ LSP server can serve hints about positional parameter names in function calls and a variable’s automatically deduced type. Inlay hints help the user not have to remember these things by heart.

Not all servers support the full set of LSP capabilities, but most of them support enough to enable the basic set of features mentioned above. Conversely, some servers offer capabilities for which no equivalent Emacs package exists yet, and so Eglot cannot (yet) expose these capabilities to Emacs users.

Next: Eglot Comman= ds, Previous: = Eglot Features, Up: Using Eglot   [Contents][Index]

3.2 Buffe= rs, Projects, and Eglot

One of the main strong points of using a language server is that a language server has a broad view of the program: it considers more than just the single source file you are editing. Ideally, the language server should know about all the source files of your program which are written in the language supported by the server. In the language-server parlance, the set of the source files of a program is known as a workspace. The Emacs equivalent of a wor= kspace is a project (see Projects= in GNU Emacs Manual). Eglot fully supports Emacs projects, and considers the file in whose buffer Eglot is turned on as belonging to a project. In the simplest case, that file is the entire project, i.e. your project consists of a single file. But there are other more complex projects:

  • A single-directory project: several source files in a single common directory.
  • A VC project: source files in a directory hierarchy under some VCS, e.g. a VCS repository (see Version Co= ntrol in GNU Emacs Manual).
  • An EDE project: source files in a directory hierarchy managed via = the Emacs Development Environment (see EDE in GNU Emacs Manual).

Eglot uses Emacs’s project management infrastructure to figure out which files and buffers belong to what project, so any kind of project supported by that infrastructure is automatically supported by Eglot.

When Eglot starts a server program, it does so in the project’s ro= ot directory, which is usually the top-level directory of the project’s directory hierarchy. This ensures the language server has the same comprehensive view of the project’s files as you do.

For example, if you visit the file ~/projects/fooey= /lib/x.foo and x.foo belongs to a project rooted at ~/projects/fooey (perhaps because a .git directory exists there), then M-x eglot causes the server pr= ogram to start with that root as the current working directory. The server then will analyze not only the file lib/x.foo you visited= , but likely also all the other *.foo files under the ~/projects/fooey directory.

In some cases, additional information specific to a given project will need to be provided to the language server when starting it. The variable eglot-workspace-configuration (see Customizing Eglot) exists f= or that purpose. It specifies the parameters and their values to communicate to each language server which needs that.

When Eglot is active for a project, it performs several background activities on behalf of the project and its buffers:

  • All of the project’s file-visiting buffers under the same major-mode are served by a single language-server connection. (If the project uses several programming languages, there will usually be a separate server connection for each group of files written in the same language and using the same Emacs major-mode.) Eglot adds the ‘[eglot:project]= ’ indication to the mode line of each such buffer, where server is the name of the = server and project identifies the project by its root directo= ry. Clicking the mouse on the Eglot mode-line indication activates a menu with server-specific items.
  • For each buffer in which Eglot is active, it notifies the language server that Eglot is managing the file visited by th= at buffer. This tells the language server that the file’s contents on disk may no longer be up-to-date due to unsaved edits. Eglot reports to the server any changes in the text of each managed buffer, to make the server aware of unsaved changes. This includes your editing of the buffer and also changes done automatically by other Emacs features and commands. Killing a buffer relinquishes its management by Eglot and notifies the server that the file on disk is up-to-date.
  • Eglot turns on a special minor mode in each buffer it manages. This minor mode ensures the server is notified about files Eglot manages, and also arranges for other Emacs features supported by Eglot (see Eglot Features) to rec= eive information from the language server, by changing the settings of these features. Unlike other minor-modes, this special minor mode is not activated manually by the user, but automatically, as the result of starting an Eglot session for the buffer. However, this minor mode provides a hook variable eglot-managed-mode-hook that can be used to cus= tomize the Eglot management of the buffer. This hook is run both when the minor mode is turned on and when it’s turned off; use the variable eglot-managed-p to tell if current buffer is st= ill being managed or not. When Eglot stops managing the buffer, this minor mode is turned off, and all the settings that Eglot changed are restored to their original values.
  • When you visit a file under the same project, whether an existing = or a new file, its buffer is automatically added to the set of buffers managed by Eglot, and the server which supports the buffer’s major-mode is notified about that. Thus, visiting a non-existent file /home/joe/projects/fooey/lib/y.foo in the above= example will notify the server of the *.foo files’ lan= guage that a new file was added to the project, even before the file appears on disk. The special Eglot minor mode is also turned on automatically in the buffer visiting the file.

Next: Eglot Varia= bles, Previous: Buffers, Projects, and Eglot, Up: Using Eglot   [Contents][Index]

3.3 Eglot Commands

This section provides a reference for the most commonly used Eglot commands:

M-x eglot<= a class=3D"copiable-link" href=3D'#index-M_002dx-eglot'> ¶<= /dt>

This command adds the current buffer and the file it visits to the group of buffers and files managed by Eglot on behalf of a suitable language server. If a language server for the buffer’s major-mode (see Major Modes in GNU Emacs Manual) is not yet running, it will be started; otherwise the buffer and its file will be added to those managed by an existing server session.

The command attempts to figure out the buffer’s major mode and the suitable language server; in case it fails, it might prompt for the major mode to use and for the server program to start. If invoked with C-u, it always prompts for the server program= , and if invoked with C-u C-u, it also prompts for the majo= r mode.

If the language server is successfully started and contacted, this command arranges for any other buffers belonging to the same project and using the same major mode to use the same language-server session. That includes any buffers created by visiting files after this command succeeds to connect to a language server.

All the Emacs features that are capable of using Eglot services (see Eglot Features) are au= tomatically configured by this command to start using the language server via Eglot. To customize which Emacs features will be configured to use Eglot, use the eglot-stay-out-of option (see Customizing Eglot).

M-x= eglot-reconnect

This command shuts down the current connection to the language server and immediately restarts it using the same options used originally. This can sometimes be useful to unclog a partially malfunctioning server connection.

M-x = eglot-shutdown

This command shuts down a language server. It prompts for a language server to shut down (unless there’s only one server session, and it manages the current buffer). Then the command shuts down the server and stops managing the buffers the server was used for. Emacs features (see Eglot Features) that Eglot configured to work with the language server are restored back to their original configuration.

Normally, this command kills the buffers used for communicating with the language server, but if invoked with a prefix argument C-u, the command doesn’t kill those buffers, allowing them to be used for diagnostics and problem reporting (see Troubleshooting Eglot).

M-x eglot-shutdown-all

This command shuts down all the language servers active in the curre= nt Emacs session. As with eglot-shutdown, invokin= g this command with a prefix argument avoids killing the buffers used for communications with the language servers.

M-x eg= lot-rename

This command renames the program symbol (a.k.a. id= entifier) at point to another name. It prompts for the new name of the symbol, and then modifies all the files in the project which are managed by the language server of the current buffer to implement the renaming.

M-x eg= lot-format

This command reformats the active region according to the language-server rules. If no region is active, it reformats the entire current buffer.

M-x eglot-format-buffer

This command reformats the current buffer, in the same manner as eglot-format does.

M-x eglot-code-actions
mouse-1

This command asks the server for any code actions<= /em> applicable at point. It can also be invoked by mouse-1 clicking= on diagnostics provided by the server.

M-x eglot-code-action-organize-imports
M-x eglot-code-action-quickfix ¶=
M-x eglot-code-action-extract
M-x eglot-code-action-inline
M-x eglot-code-action-rewrite

These commands invoke specific code actions supported by the language server.

The following Eglot commands are used less commonly, mostly for diagnostic and troubleshooting purposes:

M-x eglot-events-buffer

This command pops up the events buffer used for communication with t= he language server of the current buffer.

M-x eglot-stderr-buffer

This command pops up the buffer with the debug info printed by the language server to its standard error stream.

M-x eglot-forget-pending-continuations

Forget pending requests for the server of the current buffer.

= M-x eglot-signal-didChangeConfiguration

This command updates the language server configuration according to the current value of the variable eglot-workspace-conf= iguration (see Customizing Eglot).

M-x eglot-clear-status

Clear the last JSONRPC error for the server of the current buffer. Eglot keeps track of erroneous situations encountered by the server in its mode-line indication so that the user may inspect the communication leading up to it (see Troubleshooting Eglot). If the situation is deemed uninteresting or temporary, this command can be used to “forget” the error. Note that the command M-x eglot-reconnect can sometimes be used to unclog a temporarily malfunctioning server.

As described in Eglot Features= most features associated with Eglot are actually provided by other Emacs packages and features, and Eglot only enhances them by allowing them to use the information coming from the language servers. For completeness, here’s the list of commands of those other packages that are very commonly used in Eglot-managed buffers:

M-x eldoc

Ask the ElDoc system for help at point.

M-x flymake-show-buffer-diagnostics

Ask Flymake system to display diagnostics for the current buffer.

M-x flymake-show-project-diagnostics

Ask Flymake to list diagnostics for all the files in the current project.

M-x xref-find-definitions

Ask Xref to go the definition of the identifier at point.

M-x imenu

Let the user navigate the program source code using buffer index, categorizing program elements by syntactic class (class, method, variable, etc.) and offering completion.

M-x completion-at-point

Request completion of the symbol at point.

Previous: Eglot Co= mmands, Up: Using E= glot   [Contents][Index]

3.4 Eglot Variables

This section provides a reference for the Eglot user options.

eglot-a= utoreconnect

This option controls the ability to reconnect automatically to the language server when Eglot detects that the server process terminated unexpectedly. The default value 3 means to att= empt reconnection only if the previous successful connection lasted for more than that number of seconds; a different positive value changes the minimal length of the connection to trigger reconnection. A value of t<= /code> means always reconnect automatically, and nil means n= ever reconnect (in which case you will need to reconnect manually using M-x eglot).

e= glot-connect-timeout

This specifies the number of seconds before connection attempt to a language server times out. The value of nil me= ans never time out. The default is 30 seconds.

eglo= t-sync-connect

This setting is mainly important for connections which are slow to establish. Whereas the variable eglot-connect-timeout= controls how long to wait for, this variable controls whether to block Emacs’s user interface while waiting. The default value is 3<= /code>; a positive value means block for that many seconds, then wait for the connection in the background. The value of t means block = during the whole waiting period. The value of nil or 0 means don’t block at all during the waiting period.

eglot-events-buffer-size

This determines the size of the Eglot events buffer. See eglot-events-buffer, for how to disp= lay that buffer. If the value is changed, for it to take effect the connection should be restarted using M-x eglot-reconnect. See Troubleshooting Eglot= , for when this could be useful.

eglot-au= toshutdown

If this is non-nil, Eglot shuts down a l= anguage server when the last buffer managed by it is killed. See Shutting Down LSP Servers. The default is nil; if you want to shut down a = server, use M-x eglot-shutdown (see Eglot Commands).

eglot-confirm-server-initiated-edits

Various Eglot commands and code actions result in the language server sending editing commands to Emacs. If this option’s value is non-nil (the default), Eglot will ask for confi= rmation before performing edits initiated by the server or edits whose scope affects buffers other than the one where the user initiated the request.

eglot-ignored-server-capabilities ¶= ;

This variable’s value is a list of language server capabilitie= s that Eglot should not use. The default is nil: Eglo= t uses all of the capabilities supported by each server.

eglot-extend-to-xref

If this is non-nil, and M-. (xref-find-definitions) lands you in a file out= side of your project, such as a system-installed library or header file, transiently consider that file as managed by the same language server. That file is still outside your project (i.e. project-= find-file won’t find it), but Eglot and the server will consider it to be part of the workspace. The default is nil.

eglot-mo= de-map

This variable is the keymap for binding Eglot-related command. It is in effect only as long as the buffer is managed by Eglot. By default, it is empty, with the single exception: C-h . is r= emapped to invoke eldoc-doc-buffer. You can bind addition= al commands in this map. For example: 

  (define-key eglot-mode-map (kbd "C-=
c r") 'eglot-rename)
  (define-key eglot-mode-map (kbd "C-c o") 'eglot-code-action-org=
anize-imports)
  (define-key eglot-mode-map (kbd "C-c h") 'eldoc)
  (define-key eglot-mode-map (kbd "<f6>") 'xref-find-defini=
tions)

Additional variables, which are relevant for customizing the server connections, are documented in Customizing Eglot.

Next: Advanced server configuration, Previous: Using Eglot, Up: Eglot   [Contents][Index]

4 Customizing Eglot

Eglot itself has a relatively small number of customization options. A large part of customizing Eglot to your needs and preferences should actually be done via options of the Emacs packages and features which Eglot supports and enhances (see Eglot Features). For example:

  • To configure the face used for server-derived errors and warnings, customize the Flymake faces flymake-error and flymake-warning.
  • To configure the amount of space taken up by documentation in the echo area, customize the ElDoc variable eldoc-echo-area-use-multiline-p.
  • To completely change how ElDoc displays the at-point documentation destination, customize the ElDoc variable eldoc-display-functions.

For this reason, this manual describes only how to customize Eglot’s own operation, which mainly has to do with the server connections and the server features to be used by Eglot.

eglot-server-programs

This variable determines which language server to start for each supported major mode, and how to invoke that server’s program. See Setting Up LSP Serve= rs, for the details.

eglot-strict-mode

This is nil by default, meaning that Egl= ot is generally lenient about non-conforming servers. If you need to debug a server, set this to (disallow-non-st= andard-keys enforce-required= -keys).

eglot-server-initialized-hook

A hook run after the server object is successfully initialized.

eglot-connect-hook

A hook run after connection to the server is successfully established. See Starting Eglot= .

eglot-managed-mode-hook

A hook run after Eglot started or stopped managing a buffer. See Buffers, Projects, and Eg= lot, for details of its usage.

eglot-stay-out-of

This variable’s value lists Emacs features that Eglot shouldn&= rsquo;t automatically try to manage on the user’s behalf. It is useful, for example, when you need to use non-LSP Flymake or Company back-ends. To have Eglot stay away from some Emacs feature, add that feature’s symbol or a regexp that will match a symbol’s name to the list: for example, the symbol xref to leave Xref alone, o= r the string ‘company’ to stay away from your Co= mpany customizations. Here’s an example: 

(add-to-list 'eglot-stay-out-of 'flymake)

Note that you can still configure the excluded Emacs features manually to use Eglot in your eglot-managed-mode-hook or= via some other mechanism.

eglot-report-progress

Set this variable to true if you’d like progress notifications= coming from the LSP server to be handled as Emacs’s progress reporting facilities.

Next: Troub= leshooting Eglot, Previous: Customizing Eglot, Up: Eglot   [Contents][Index]

5 Advanced ser= ver configuration

Though many language servers work well out-of-the-box, most allow fine-grained control of their operation via specific configuration options that vary from server to server. A small number of servers require such special configuration to work acceptably, or even to work at all.

After having setup a server executable program in eglot-server-programs (see Setting Up LSP Servers) and ensuring Eglot can invoke it, you may want to take advantage of some of these options. You should first distinguish two main kinds of server configuration:

  • Project-specific, applying to a specific project;
  • User-specific, applying to all projects the server is used for.

When you have decided which kind you need, the following sections teach how Eglot’s user variables can be used to achieve it:

It’s important to note that not all servers allow both kinds of configuration, nor is it guaranteed that user options can be copied over to project options, and vice-versa. When in doubt, consult your language server’s documentation.

It’s also worth noting that some language servers can read these settings from configuration files in the user’s = HOME directory or in a project’s directory. For example, the pylsp Python server reads the file ~/.config/pycodestyle for= user configuration. The clangd C/C++ server read= s both ~/.config/clangd/config.yaml for user configura= tion and .clangd for project configuration. It may be a= dvantageous to use these mechanisms instead of Eglot’s, as the latter have the advantage of working with other LSP clients.

Next: User-specific configuration, Up: Advanced server configuration &nbs= p; [= Contents][Index]

5.1 Proje= ct-specific configuration

To set project-specific settings, which the LSP specification calls workspace configuration, the variable eglot-workspace-configuration may be used.

This variable is a directory-local variable (see Per-directory Local Variables in The GNU Emacs Manual). It’s important to recognize that this variable reall= y only makes sense when set directory-locally. It usually does not make sense to set it file-locally or in a major-mode hook.

The most common way to set eglot-workspace-configur= ation is using a .dir-locals.el file in the root of your= project. If you can’t do that, you may also set it from Elisp code via the dir-locals-set-class-variables function. (see = Directory Local Variables in GNU Emacs Lisp Reference Manual= ).

However you choose to set it, the variable’s value is a plist (see Property Lists in GNU Emacs Lisp Reference Manual) with the following format: 

 (:server1 plist1 :server2 plist2 …)

Here, :server1 and :server2<= /var> are keywords whose names identify the LSP language servers to target. Consult server documentation to find out what name to use. plist1 and plist2 are plists of options, possibly nesting oth= er plists.

When experimenting with workspace settings, you can use the command M-x eglot-show-workspace-configuration to inspect = and debug the value of this variable in its final JSON form, ready to be sent to the server (see JSONRPC o= bjects in Elisp). This helper command works even before actually connecting to the server.

These variable’s value doesn’t take effect immediately. Tha= t happens upon establishing the connection, in response to an explicit query from the server, or when issuing the command M-x eglot-signal-didChangeConfiguration which notifies the server during an ongoing Eglot session.

5.1.1 Examples

For some users, setting eglot-workspace-configurati= on is a somewhat daunting task. One of the reasons is having to manage the general Elisp syntax of per-mode directory-local variables, which uses alists (see Association Lists i= n GNU Emacs Lisp Reference Manual), and the specific syntax of Eglot’s variable, which us= es plists. Some examples are useful.

Let’s say you want to configure two language servers to be used in= a project written in a combination of the Python and Go languages. You want to use the pylsp and gopls LSP servers. In the documentation of the servers in question (or in some other editor&rsquo= ;s configuration file, or in some blog article), you find the following configuration options in informal dotted-notation syntax: 

pylsp.plugins.jedi_completion.include_p=
arams: true
pylsp.plugins.jedi_completion.fuzzy: true
pylsp.pylint.enabled: false
gopls.usePlaceholders: true

To apply this to Eglot, and assuming you chose the .dir-locals.el file method, the contents of tha= t file could be: 

((nil
  . ((eglot-workspace-configuration
      . (:pylsp (:plugins (:jedi_completion (:include_params t
                                             :fuzzy t)
                           :pylint (:enabled :json-false)))
         :gopls (:usePlaceholders t)))))
 (python-mode . ((indent-tabs-mode . nil)))
 (go-mode     . ((indent-tabs-mode . t))))

This sets the value of eglot-workspace-configuratio= n in all the buffers inside the project; each server will use only the section of the parameters intended for that server, and ignore the rest. Note how alists are used for associating Emacs mode names with alists associating variable names with variable values. Then notice how plists are used inside the value of eglot-workspace-configuration.

This following form may also be used: 

((python-mode
  . ((eglot-workspace-configuration
      . (:pylsp (:plugins (:jedi_completion (:include_params t
                                             :fuzzy t)
                           :pylint (:enabled :json-false)))))
     (indent-tabs-mode . nil)))
 (go-mode
  . ((eglot-workspace-configuration
      . (:gopls (:usePlaceholders t)))
     (indent-tabs-mode . t))))

This sets up the value of eglot-workspace-configura= tion separately depending on the major mode of each of that project’s buffers. python-mode buffers will have the var= iable set to (:pylsp (:plugins ...)). = go-mode buffers will have the variable set to (:gopls (:usePlaceholders t)).

Some servers will issue workspace configuration for specific files inside your project. For example, if you know gopls is asking about specific files in the src/imported subdir= ectory and you want to set a different option for gopls.usePlaceholde= rs , you may use something like: 

((python-mode
  . ((eglot-workspace-configuration
      . (:pylsp (:plugins (:jedi_completion (:include_params t
                                             :fuzzy t)
                           :pylint (:enabled :json-false)))))
     (indent-tabs-mode nil)))
 (go-mode
  . ((eglot-workspace-configuration
      . (:gopls (:usePlaceholders t)))
     (indent-tabs-mode t)))
 ("src/imported"
   . ((eglot-workspace-configuration
      . (:gopls (:usePlaceholders nil))))))

Finally, if one needs to determine the workspace configuration based on some dynamic context, eglot-workspace-configuration= can be set to a function. The function is called with the eglot-lsp-server instance of the connected serv= er (if any) and with default-directory set to the root of the p= roject. The function should return a plist suitable for use as the variable’s value.

Next: JS= ONRPC objects in Elisp, Previous: Project-specific configuration,= Up: = Advanced server configuration   [Contents][Index]

5.2 User-spe= cific configuration

This kind of configuration applies to all projects the server is used for. Here, there are a number of ways to do this inside Eglot.

A common way is to pass command-line options to the server invocation via eglot-server-programs. Let’s say we = want to configure where the clangd server reads its compile_commands.json from. This can be done l= ike so: 

(with-eval-after-load 'eglot
  (add-to-list 'eglot-server-programs
               `(c++-mode . ("clangd" "--compile-commands-di=
r=3D/tmp"))))

Another way is to have Eglot pass a JSON object to the server during the LSP handshake. This is done using the :initializationOptions syntax of eglot-server-programs: 

(with-eval-after-load 'eglot
  (add-to-list 'eglot-server-programs
               `(c++-mode . ("clangd" :initializationOptions
                                      (:compilationDatabasePath "/tmp&=
quot;)))))

The argument (:compilationDatabasePath "/tmp&q= uot;) is Emacs’s representation in plist format of a simple JSON object {"compilationDatabasePath": "/tmp"= }. To learn how to represent more deeply nested options in this format, See JSONRPC objects in Elisp.

In this case, the two examples achieve exactly the same, but notice how the option’s name has changed between them.

Finally there is another way to do user-specific configuration of language servers, which may be used if the methods above are not supported. It consists of globally setting eglot-workspace-configuration, a variable origi= nally intended for project-specific configuration. This has the same effect as giving all your projects a certain default configuration, as described in See Proje= ct-specific configuration. Here is an example: 

(setq-default eglot-workspace-configuration
              '(:pylsp (:plugins (:jedi_completion (:include_params t
                                                    :fuzzy t)
                                  :pylint (:enabled :json-false)))
                :gopls (:usePlaceholders t)))

Note that the global value of eglot-workspace-confi= guration is always overriden if a directory-local value is detected.

Previous: User-specific configuration, Up: Advanced server configuration=   [Contents][Index]

5.3 JSONRPC objects= in Elisp

Emacs’s preferred way of representing JSON is via Lisp lists. In Eglot, the syntax of this list is the simplest possible (the one with fewer parenthesis), a plist (see Prope= rty Lists in GNU Emacs Lisp Reference Manual).

The plist may be arbitrarily complex, and generally containing other keyword-value property sub-plists corresponding to JSON sub-objects.

For representing the JSON leaf values true, = false, null and {}, you ca= n use the Lisp values t, :json-false, nil, a= nd eglot-{}, respectively. JSON arrays are represented as lisp vectors surrounded by square brackets (see Vectors in GNU = Emacs Lisp Reference Manual).

For example, the plist 

(:pylsp (:plugins (:jedi_completion (:incl=
ude_params t
                                     :fuzzy t)
                   :pylint (:enabled :json-false
                            :args ["--disable" "C0103"]=
)))
 :gopls (:usePlaceholders t))

is serialized by Eglot to the following JSON text: 

{
  "pylsp": {
    "plugins": {
      "jedi_completion": {
        "include_params": true,
        "fuzzy": true
      },
      "pylint": {
        "enabled": false,
        "args": [
          "--disable",
          "C0103"
        ]
      }
    }
  },
  "gopls": {
    "usePlaceholders":true
  },
}

Next: GNU Free Documentation License, Previous: Advanced server configuratio= n, Up: Eglot   [Conten= ts][Index]

6 Troubleshooting Eglo= t

This section documents commands and variables that can be used to troubleshoot Eglot problems. It also provides guidelines for reporting Eglot bugs in a way that facilitates their resolution.

When you encounter problems with Eglot, try first using the commands M-x eglot-events-buffer and M-x= eglot-stderr-buffer. They pop up special buffers that can be used to inspect the communications between the Eglot and language server. In many cases, this will indicate the problems or at least provide a hint.

A common and easy-to-fix cause of performance problems is the length of these two buffers. If Eglot is operating correctly but slowly, customize the variable eglot-events-buffer-size= (see Eglot Variables) to = limit logging, and thus speed things up.

If you need to report an Eglot bug, please keep in mind that, because there are so many variables involved, it is generally both very difficult and absolutely essenti= al to reproduce bugs exactly as they happened to you, the user. Therefore, every bug report should include:

  1. The transcript of events obtained from the buffer popped up by M-x eglot-events-buffer. If the transcript can be= narrowed down to show the problematic exchange, so much the better. This is invaluable for the investigation and reproduction of the problem.
  2. If Emacs signaled an error (an error message was seen or heard), = make sure to repeat the process after toggling debug-on-err= or on (via M-x toggle-debug-on-error). This normally pr= oduces a backtrace of the error that should also be attached to the bug report.
  3. An explanation of how to obtain, install, and configure the langu= age server you used. If possible, try to replicate the problem with the C/C++ or Python servers, as these are very easy to= install.
  4. A description of how to setup the minimal= project (one or two files and their contents) where the problem happens.
  5. A recipe to replicate the problem with a clean= Emacs run. This means emacs -Q invocation or a very minimal (no mo= re that 10 lines) .emacs initialization file. eglot-ensure and use-package calls are generally not needed.
  6. Make sure to double check all the above elements and re-run the recipe to see that the problem is reproducible.

Please keep in mind that some problems reported against Eglot may actually be bugs in the language server or the Emacs feature/package that used Eglot to communicate with the language server.

Next: Index, Previous: = Troubleshoo= ting Eglot, Up: Eglot &= nbsp; [Contents][Index= ]

Appendix A G= NU Free Documentation License

Version 1.3, 3 November 2008 
Copyright © 2000, 2001, 2002, 2007=
, 2008 Free Software Foundation, Inc.
https://fsf.org/

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
  1. PREAMBLE

    The purpose of this License is to make a manual, textbook, or other functional and useful document free in the sense of = freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.

    This License is a kind of “copyleft”, which means that deriv= ative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.

    We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.

  2. APPLICABILITY AND DEFINITIONS

    This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The “Document”, below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as “you”. You accept the license if= you copy, modify or distribute the work in a way requiring permission under copyright law.

    A “Modified Version” of the Document means any work containi= ng the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.

    A “Secondary Section” is a named appendix or a front-matter = section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document’s overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.

    The “Invariant Sections” are certain Secondary Sections whos= e titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.

    The “Cover Texts” are certain short passages of text that ar= e listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.

    A “Transparent” copy of the Document means a machine-readabl= e copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not “Transparent” is called “Opa= que”.

    Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.

    The “Title Page” means, for a printed book, the title page i= tself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, “Title Page” = means the text near the most prominent appearance of the work’s title, preceding the beginning of the body of the text.

    The “publisher” means any person or entity that distributes = copies of the Document to the public.

    A section “Entitled XYZ” means a named subunit of the Docume= nt whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as “Acknowledgements&rdqu= o;, “Dedications”, “Endorsements”, or “History&rd= quo;.) To “Preserve the Title” of such a section when you modify the Document means that it remains a section “Entitled XYZ” according to this definition.

    The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.

  3. VERBATIM COPYING

    You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.

    You may also lend copies, under the same conditions stated above, and you may publicly display copies.

  4. COPYING IN QUANTITY

    If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document’s license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.

    If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.

    If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.

    It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.

  5. MODIFICATIONS

    You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:

    1. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.
    2. List on the Title Page, as authors, one or more persons or entiti= es responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement.
    3. State on the Title page the name of the publisher of the Modified Version, as the publisher.
    4. Preserve all the copyright notices of the Document.
    5. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.
    6. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.
    7. Preserve in that license notice the full lists of Invariant Secti= ons and required Cover Texts given in the Document’s license notice.
    8. Include an unaltered copy of this License.
    9. Preserve the section Entitled “History”, Preserve its= Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled “History” in the Document, create = one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.
    10. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the “History” section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.
    11. For any section Entitled “Acknowledgements” or &ldquo= ;Dedications”, Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.
    12. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.
    13. Delete any section Entitled “Endorsements”. Such a s= ection may not be included in the Modified Version.
    14. Do not retitle any existing section to be Entitled “Endorse= ments” or to conflict in title with any Invariant Section.
    15. Preserve any Warranty Disclaimers.

    If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version’s license notice. These titles must be distinct from any other section titles.

    You may add a section Entitled “Endorsements”, provided it c= ontains nothing but endorsements of your Modified Version by various parties—for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.

    You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.

    The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.

  6. COMBINING DOCUMENTS

    You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.

    The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.

    In the combination, you must combine any sections Entitled “Histor= y” in the various original documents, forming one section Entitled “History”; likewise combine any sections Entitled “Acknow= ledgements”, and any sections Entitled “Dedications”. You must delete all sections Entitled “Endorsements.”

  7. COLLECTIONS OF DOCUMENTS

    You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.

    You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.

  8. AGGREGATION WITH INDEPENDENT WORKS

    A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an “aggregate” if the copyright resulting from the compilation is not used to limit the legal rights of the compilation’s users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.

    If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document’s Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.

  9. TRANSLATION

    Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.

    If a section in the Document is Entitled “Acknowledgements”, “Dedications”, or “History”, the requirement (secti= on 4) to Preserve its Title (section 1) will typically require changing the actual title.

  10. TERMINATION

    You may not copy, modify, sublicense, or distribute the Document except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, or distribute it is void, and will automatically terminate your rights under this License.

    However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation.

    Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice.

    Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, receipt of a copy of some or all of the same material does not give you any rights to use it.

  11. FUTURE REVISIONS OF THIS LICENSE

    The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See https://www.gnu.or= g/licenses/.

    Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License “or any later version” applies to it, you have the opti= on of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. If the Document specifies that a proxy can decide which future versions of this License can be used, that proxy’s public statement of acceptance of a version permanently authorizes you to choose that version for the Document.

  12. RELICENSING

    “Massive Multiauthor Collaboration Site” (or “MMC Site= ”) means any World Wide Web server that publishes copyrightable works and also provides prominent facilities for anybody to edit those works. A public wiki that anybody can edit is an example of such a server. A “Massive Multiauthor Collaboration” (or “MMC”) cont= ained in the site means any set of copyrightable works thus published on the MMC site.

    “CC-BY-SA” means the Creative Commons Attribution-Share Alik= e 3.0 license published by Creative Commons Corporation, a not-for-profit corporation with a principal place of business in San Francisco, California, as well as future copyleft versions of that license published by that same organization.

    “Incorporate” means to publish or republish a Document, in w= hole or in part, as part of another Document.

    An MMC is “eligible for relicensing” if it is licensed under= this License, and if all works that were first published under this License somewhere other than this MMC, and subsequently incorporated in whole or in part into the MMC, (1) had no cover texts or invariant sections, and (2) were thus incorporated prior to November 1, 2008.

    The operator of an MMC Site may republish an MMC contained in the site under CC-BY-SA on the same site at any time before August 1, 2009, provided the MMC is eligible for relicensing.

ADDENDUM: How to use this License for your documents

To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page: 

  Copyright (C)  <=
var class=3D"var">year  your name.
  Permission is granted to copy, distribute and/or modify this document
  under the terms of the GNU Free Documentation License, Version 1.3
  or any later version published by the Free Software Foundation;
  with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
  Texts.  A copy of the license is included in the section entitled ``GNU
  Free Documentation License''.

If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the “with…Texts.” line with this: 

    with the Invar=
iant Sections being list their titles, with
    the Front-Cover Texts being list, and with the=
 Back-Cover Texts
    being list.

If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation.

If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.

Previous: GNU Free Documentation License, Up: Eglot   [Contents][Index]

Index

=
Jump to:   A=  =20 B=  =20 C=  =20 D=  =20 E=  =20 F=  =20 I=  =20 L=  =20 M=  =20 O=  =20 P=  =20 Q=  =20 S=  =20 T=  =20 V=  =20 W=  =20 X=  =20
= = Eglot Var= iables= = =  <= td> <= td> Eglot Comm= andsEglot Comm= ands<= td> 
Index Entry&n= bsp; Section
A
activating Eglot for a project: = Sta= rting Eglot
B
buffers managed by Eglot: Eglot and Bu= ffers
C
code actions: Eglot Features
command-line arguments: User-specific configuration
commands, Eglot: Eglot Commands
customizing Eglot: Customizing Eglot
D
documentation using Eglot: Eglot Command= s
E
= eglot: Starting Eglot
eglot-autoreconnect: Eglot V= ariables
eglot-autoshutdown: 
eglot-confirm-server-i= nitiated-edits: Eglot Variables
eglot-connect-hook: Cus= tomizing Eglot
eglot-connect-timeout:&nb= sp;Eglot Variables
eglot-ensure: Starting Eglot
eglot-events-buffer-size: Eglot Variables
eglot-extend-to-xref:&= nbsp;Eglot Variables
eglot-ignored-server-capabili= ties: = Eglot Variables
eglot-managed-mode-hook: Eglot and Buffers
eglot-managed-p: Eglot and= Buffers
eglot-menu: Eglot and Buffers
eglot-mode-map: Eglot Variabl= es
eglot-report-progress:&nb= sp;Customizing Eglot
eglot-server-initialized-hook: Customizing Eglot
eglot-server-programs:&nb= sp;Setting Up LSP Servers
eglot-show-workspace-configu= ration: Project-specific configur= ation
eglot-shutdown: Shutti= ng Down LSP Servers
eglot-stay-out-of: <= /td>C= ustomizing Eglot
eglot-strict-mode: Custo= mizing Eglot
eglot-sync-connect: Eglot= Variables
eglot-workspace-configuration<= /a>: Project-specific configuration
eglot-workspace-configuration: User-specific configuration
eldoc, and Eglot: Eglot Commands
F
features in buffers supported by Eglot= : Eglot Features
finding definitions of identifiers= using Eglot: Eglot Commands
flymake, and Eglot: Eglot Commands
I
imenu navigation using Eglot: Eglot C= ommands
initializationOptions: User= -specific configuration
L
language server for Eglot: Setti= ng Up LSP Servers
language server protocol: Top
LS= P: Top
LSP server for Eglot, setting up:Setting Up LSP Servers
M
M-x eglot: Eglot Commands
M-x eglot-clear-status:Eglot Commands
M-x eglot-code-action-extract= : Eglot Commands
M-x eglot-code-action-inline: Eglot Commands
M-x eglot-code-a= ction-organize-imports: Eglot Commands
M-x eglot-code-action-quickf= ix: Eglot Commands
M-x eglot-code-action-rewrite= : Eglot Commands
M-x eglot-code-actions:Eglot Commands
M-x eglot-events-buffer: Eglot Commands
M-x eglot-forget-pen= ding-continuations: Eglot Commands
M-x eglot-format: 
M-x eglot-format-buffer: Eglot Commands
M-x eglot-reconnect: <= /td>Eglo= t Commands
M-x eglot-rename: 
M-x eglot-shutdown: Eglot = Commands
M-x eglot-shutdown-all:Eglot Commands
M-x eglot-signal-didCha= ngeConfiguration: Eglot Commands
M-x eglot-stderr-buffer: Eglot Commands
mode-line indication of language serv= er: Eglot and Buffers
mouse clicks on mode-line, and Eglot= : Eglot and Buffers
mouse-1: Eglot Commands
O
on-the-fly diagnostics using Eglot= : Eglot Commands
P
progress: = Customizing Eglot
projects and Eglot: Eglot and Buffers
Q
quick start: Quick Start
S
setting up LSP server for Eglot:&nbs= p;Setting Up LSP Servers
shutting down LSP server: Shut= ting Down LSP Servers
starting Eglot: Starting Eglot
symbol completion using Eglot: Eglot= Commands
T
troubleshooting Eglot: Troubleshootin= g Eglot
V
variables, Eglot: Eglot Variables
W
workspace: Eglot and Buffers
workspace configuration: Project-specific configuration
X
xref, and Eglot: Eglot Commands
=
Jump to:   A=  =20 B=  =20 C=  =20 D=  =20 E=  =20 F=  =20 I=  =20 L=  =20 M=  =20 O=  =20 P=  =20 Q=  =20 S=  =20 T=  =20 V=  =20 W=  =20 X=  =20

Footnotes

(1)=

A polyglot is a person who is able to use several languages.

--=-=-=--