Update markdown, add Tips & Tricks (#505)

* Update markdown, add Tips & Tricks This updates some little but important things here: - Removes hand-written TOC (GitHub makes its own now) - Add NonGNU Elpa - Update installation instructions - Mention elixir-ts-mode (Emacs 29+) - Add Tips & Tricks section * Add trick for multiple syntaxes * Update README.md Co-authored-by: Walter McGinnis <[email protected]> * Update README.md --------- Co-authored-by: Walter McGinnis <[email protected]>
elixir-editors · Jun 26, 2023 · 19ed1ff · 19ed1ff
1 parent 8ac787f
commit 19ed1ff
Showing 1 changed file with 102 additions and 41 deletions.
diff --git a/README.md b/README.md
@@ -1,38 +1,28 @@
 [![License GPL 3][badge-license]](http://www.gnu.org/licenses/gpl-3.0.txt)
 [![Build Status](https://github.com/elixir-editors/emacs-elixir/actions/workflows/ci.yml/badge.svg)](https://github.com/elixir-editors/emacs-elixir/actions)
+[![NonGNU ELPA](https://elpa.nongnu.org/nongnu/elixir-mode.svg)](https://elpa.nongnu.org/nongnu/elixir-mode.html)
 [![MELPA Stable](http://stable.melpa.org/packages/elixir-mode-badge.svg)](http://stable.melpa.org/#/elixir-mode)
 [![MELPA](http://melpa.org/packages/elixir-mode-badge.svg)](http://melpa.org/#/elixir-mode)
 
+> **WARNING**
+> There is a built-in Elixir mode with tree-sitter support from Emacs 30+ that can also be used with Emacs 29
+> This repository is for an older elixir-mode built with SMIE (Simple Minded Indentation Engine) which is not
+> as advanced as tree-sitter for a language like Elixir.
+
 # Elixir Mode
 
 Provides font-locking, indentation and navigation support for the
 [Elixir programming language.](http://elixir-lang.org/)
 
-- [Installation](#installation)
-  - [Via package.el](#via-packageel)
-  - [Via el-get](#via-el-get)
-  - [Manual](#manual)
-- [Usage](#usage)
-  - [Interactive Commands](#interactive-commands)
-  - [Configuration](#configuration)
-  - [Keymapping](#keymapping)
-- [Notes](#notes)
-- [Elixir Tooling Integration](#elixir-tooling-integration)
-- [Elixir Format](#elixir-format)
-- [Treesitter Support](#treesitter-support)
-- [History](#history)
-- [Contributing](#contributing)
-- [License](#license)
-
 ## Installation
 
+`elixir-mode` is available on [NON-GNU ELPA](https://elpa.nongnu.org/), 
+[MELPA STABLE](https://stable.melpa.org/) and [MELPA](https://melpa.org/).
+
 ### Via package.el
 
 `package.el` is the built-in package manager in Emacs.
 
-`elixir-mode` is available on the two major community maintained repositories -
-[MELPA STABLE](https://stable.melpa.org/) and [MELPA](https://melpa.org/).
-
 You can install `elixir-mode` with the following command:
 
 <kbd>M-x package-install [RET] elixir-mode [RET]</kbd>
@@ -52,20 +42,20 @@ If the installation doesn't work try refreshing the package list:
 Keep in mind that MELPA packages are built automatically from
 the `master` branch, meaning bugs might creep in there from time to
 time. Never-the-less, installing from MELPA is the recommended way of
-obtaining `Elixir-Mode`, as the `master` branch is normally quite stable and
-"stable" (tagged) builds are released somewhat infrequently.
+obtaining `Elixir-Mode`.
 
-With the most recent builds of Emacs, you can pin `Elixir-Mode` to always
-use MELPA Stable by adding this to your Emacs initialization:
+MELPA Stable contains packages released from our tags.
 
-### Manual
+### Via use-package
 
-You can install `Elixir-Mode` manually by placing `Elixir-Mode` on your `load-path` and
-`require` ing it. Many people favour the folder `~/.emacs.d/vendor`.
+Since Emacs 29, `use-package` is a built-in feature. For versions prior to 29 
+one can also install it from MELPA (and MELPA Stable).
 
-```el
-(add-to-list 'load-path "~/.emacs.d/vendor")
-(require 'elixir-mode)
+To install elixir-mode using `use-package` one can:
+
+``` elisp
+(use-package elixir-mode
+  :ensure t)
 ```
 
 ## Usage
@@ -141,20 +131,17 @@ This package is tested only with a single version of OTP and 3 versions of Elixi
 
 ## Elixir Tooling Integration
 
-If you looking for elixir tooling integration for Emacs, check: [alchemist.el](https://github.com/tonini/alchemist.el)
-
 You can use [web-mode.el](http://web-mode.org) to edit elixir templates (eex files).
 
 [mix.el](https://github.com/ayrat555/mix.el) provides a minor mode for integration with Mix, a build tool that ships with Elixir.
 
+[exunit.el](https://github.com/ananthakumaran/exunit.el) provides `ExUnit` integration.
 
 ## Elixir Format
 
-``` elisp
-M-x elixir-format
-```
+This mode can call mix for formatting code. When inside an elixir buffer, just type `M-x elixir-format`.
 
-### Add elixir-mode hook to run elixir format on file save
+To automate that, you can add this command to the `before-save` hook.
 
 ``` elisp
 ;; Create a buffer-local hook to run elixir-format on save, only when we enable elixir-mode.
@@ -180,25 +167,99 @@ or you set `elixir-format-arguments` in a hook like this:
 ```
 
 In this example we use [Projectile](https://github.com/bbatsov/projectile) to determine if we are in a project and then set `elixir-format-arguments` accordingly.
+
 Please note that this code snippet may cause unhappiness if there is no `.formatter.exs` file available.
 
-## Treesitter Support
+## Tips & Tricks
+
+### Prettify symbols
+
+Emacs supports [font ligatures](https://en.wikipedia.org/wiki/Ligature_(writing)). For enabling it for Elixir 
+you can add it to your configuration:
 
-There is a work-in-progress mode that uses Tree-Sitter instead of SMIE. If you are on Emacs 29.x you can try it out [wkirschbaum/elixir-ts-mode](https://github.com/wkirschbaum/elixir-ts-mode).
+``` elisp
+(add-hook
+ 'elixir-mode-hook
+ (lambda ()
+   (push '(">=" . ?\u2265) prettify-symbols-alist)
+   (push '("<=" . ?\u2264) prettify-symbols-alist)
+   (push '("!=" . ?\u2260) prettify-symbols-alist)
+   (push '("==" . ?\u2A75) prettify-symbols-alist)
+   (push '("=~" . ?\u2245) prettify-symbols-alist)
+   (push '("<-" . ?\u2190) prettify-symbols-alist)
+   (push '("->" . ?\u2192) prettify-symbols-alist)
+   (push '("<-" . ?\u2190) prettify-symbols-alist)
+   (push '("|>" . ?\u25B7) prettify-symbols-alist)))
+   
+;; Or if you use use-packge
+
+(use-package elixir-mode
+ :hook (elixir-mode . (lambda ()
+    (push '(">=" . ?\u2265) prettify-symbols-alist)
+    (push '("<=" . ?\u2264) prettify-symbols-alist)
+    (push '("!=" . ?\u2260) prettify-symbols-alist)
+    (push '("==" . ?\u2A75) prettify-symbols-alist)
+    (push '("=~" . ?\u2245) prettify-symbols-alist)
+    (push '("<-" . ?\u2190) prettify-symbols-alist)
+    (push '("->" . ?\u2192) prettify-symbols-alist)
+    (push '("<-" . ?\u2190) prettify-symbols-alist)
+    (push '("|>" . ?\u25B7) prettify-symbols-alist))))
+```
+
+### Formatting
+
+If you have issues with the formatter provided by this package, you can try
+using the format function of language servers. Elixir-ls supports this.
+
+One way to configure this with `eglot` and `use-package` would be:
+
+``` elisp
+(use-package elixir-mode
+ :hook (elixir-mode . eglot-ensure)
+ (before-save . eglot-format))
+```
+
+### Syntax highlighting for LiveView (and similar techniques for other syntaxes)
+
+When you need different major modes in the SAME buffer, Emacs do not provide a standard way. 
+There is an external package that can help here by adding more than one major mode called `poly-mode`.
+
+A possible configuration would be:
+
+``` elisp
+;; Assumes web-mode and elixir-mode are already set up
+;;
+(use-package polymode
+  :mode ("\.ex$" . poly-elixir-web-mode)
+  :config
+  (define-hostmode poly-elixir-hostmode :mode 'elixir-mode)
+  (define-innermode poly-liveview-expr-elixir-innermode
+    :mode 'web-mode
+    :head-matcher (rx line-start (* space) "~H" (= 3 (char "\"'")) line-end)
+    :tail-matcher (rx line-start (* space) (= 3 (char "\"'")) line-end)
+    :head-mode 'host
+    :tail-mode 'host
+    :allow-nested nil
+    :keep-in-mode 'host
+    :fallback-mode 'host)
+  (define-polymode poly-elixir-web-mode
+    :hostmode 'poly-elixir-hostmode
+    :innermodes '(poly-liveview-expr-elixir-innermode))
+  )
+(setq web-mode-engines-alist '(("elixir" . "\\.ex\\'")))
+```
 
 ## History
 
-This mode is based on the
-[Emacs mode by secondplanet](https://github.com/secondplanet/elixir-mode).
+This mode is based on the [Emacs mode by secondplanet](https://github.com/secondplanet/elixir-mode).
 
 ## Contributing
 
 Please read [CONTRIBUTING.md](https://github.com/elixir-editors/emacs-elixir/blob/master/CONTRIBUTING.md) for guidelines on how to contribute to this project.
 
 ## License
 
-Copyright © 2011-2017 Samuel Tonini, Matt DeBoard, Andreas Fuchs, secondplanet and
-[contributors](https://github.com/elixir-editors/emacs-elixir/contributors).
+Copyright © 2011-2017 Samuel Tonini, Matt DeBoard, Andreas Fuchs, secondplanet and [contributors](https://github.com/elixir-editors/emacs-elixir/contributors).
 
 Distributed under the GNU General Public License, version 3