From ed770a92c3bdf7a5c9a64a01cf75d875bc0eb56a Mon Sep 17 00:00:00 2001
From: Steve Cohen <scohen@scohen.org>
Date: Thu, 22 Jun 2023 09:12:35 -0700
Subject: [PATCH] Docs: Installation (#229)

* Added installation instructions for emacs / vscode

Initial installation instructions for emacs and vscode.

* Fixed unmatched close quote

This was flagged by `mix docs`
---
 README.md                                     |  3 +-
 .../remote_control/plugin/discovery.ex        |  2 +-
 mix.exs                                       |  8 +-
 pages/installation.md                         | 93 +++++++++++++++++++
 4 files changed, 102 insertions(+), 4 deletions(-)
 create mode 100644 pages/installation.md

diff --git a/README.md b/README.md
index 530bb2bfb..d7ba1d50e 100644
--- a/README.md
+++ b/README.md
@@ -55,7 +55,8 @@ fix typos, warnings, unused variables and a whole host of errors when they occur
 faster.
 
 ## Installation
-To install lexical fetch the source code from git, then do the following:
+
+Follow the [Detailed Installation Instructions](pages/installation.md)
 
  ```
 make release.namespaced
diff --git a/apps/remote_control/lib/lexical/remote_control/plugin/discovery.ex b/apps/remote_control/lib/lexical/remote_control/plugin/discovery.ex
index 4aac6b1e9..6ff285484 100644
--- a/apps/remote_control/lib/lexical/remote_control/plugin/discovery.ex
+++ b/apps/remote_control/lib/lexical/remote_control/plugin/discovery.ex
@@ -6,7 +6,7 @@ defmodule Lexical.RemoteControl.Plugin.Discovery do
   If a plugin is found, the app is then registered with the plugin system.
 
   If we're running in a namespaced build, we must apply the same namespace to the plugin's modules, or it
-  will be looking for structs like `Lexical.Document', and be passed in structs like `LXRelease.Document`,
+  will be looking for structs like `Lexical.Document`, and be passed in structs like `LXRelease.Document`,
   and the plugin will crash.
   """
   alias Lexical.Plugin
diff --git a/mix.exs b/mix.exs
index 9a2ee1e5a..94f58a7bc 100644
--- a/mix.exs
+++ b/mix.exs
@@ -28,9 +28,13 @@ defmodule Lexical.LanguageServer.MixProject do
 
   defp docs do
     [
-      main: "Lexical",
+      main: "readme",
       deps: [jason: "https://hexdocs.pm/jason/Jason.html"],
-      extras: ~w(README.md pages/architecture.md),
+      extras: ~w(
+        README.md
+        pages/installation.md
+        pages/architecture.md
+      ),
       filter_modules: fn mod_name, _ ->
         case Module.split(mod_name) do
           ["Lexical", "Protocol", "Requests" | _] -> true
diff --git a/pages/installation.md b/pages/installation.md
new file mode 100644
index 000000000..41b872a15
--- /dev/null
+++ b/pages/installation.md
@@ -0,0 +1,93 @@
+# Installation
+
+The following instructions document how to install Lexical after
+building from source. Some editors, like Visual Studio Code, have the
+ability to automatically install the latest version of Lexical for
+you.
+
+## Caveats
+
+ * Presently, Lexical only works on Elixir 1.14 under Erlang 25. Our
+aim in the near future is to support Elixir 1.13 to 1.15 and erlang
+versions >= 24. Pull requests gladly accepted.
+
+ * While it's within Lexical's capabilities to run your project in a
+ different elixir and erlang version than Lexical is built with,
+ presently, we don't support running your project in a different
+ elixir and or erlang version.  We aim to fix this very shortly, as
+ this dramatically limits Lexical's usefulness when working with
+ multiple projects.
+
+
+## Prerequisites
+
+The first step in getting Lexical running locally is to clone the git
+repository. Do this with
+
+```elixir
+git clone git@github.com:lexical-lsp/lexical.git
+```
+
+Then change to the lexical directory
+```shell
+cd lexical
+```
+...and build the project
+
+```shell
+make release.namespaced
+```
+
+If things complete successfully, you will then have a release in your
+`build/dev/rel/lexical` directory. If you see errors, please file a
+bug.
+
+For the following examples, assume the absolute path to your Lexical
+source code is `/my/home/projects/lexical`.
+
+## Editor-specific setup
+1. [Vanilla Emacs with lsp-mode](#vanilla-emacs-with-lsp-mode)
+2. [Vanilla Emacs with eglot](#vanilla-emacs-with-eglot)
+3. [Visual Studio Code](#visual-studio-code)
+
+## Vanilla Emacs with lsp-mode
+The emacs instructions assume you're using `use-package`, which you
+really should be. In your `.emacs.d/init.el` (or wherever you put your
+emacs configuration), insert the following code:
+
+```lisp
+(use-package lsp-mode
+  :ensure t
+  :config
+  (setq lsp-modeline-code-actions-segments '(count icon name))
+
+  :init
+  '(lsp-mode))
+
+
+(use-package elixir-mode
+  :ensure t
+  :custom
+  (lsp-elixir-server-command '("/my/home/projects/_build/dev/rel/lexical/start_lexical.sh")))
+
+```
+
+Restart emacs, and Lexical should start when you open a file with a
+`.ex` extension.
+
+
+## Vanilla Emacs with eglot
+
+Eglot has a couple of utf8 related bugs that make it fail with
+Lexical, and is not supported at this time.
+
+
+## Visual Studio Code
+
+Click on the extensions button on the sidebar, then search for
+`lexical`, then click `install`.  By default, the extension will automatically
+download the latest version of Lexical.
+
+To change to a local executable, go to `Settings -> Extensions -> Lexical` and
+type `/my/home/projects/lexical/_build/dev/rel/lexical` into the text box in
+the `Server: Release path override` section.