branch: elpa/haskell-ts-mode
commit bd875a2bfb83fe5f4795a0a8e236a7c06d22a990
Author: Dominik Schrempf <dominik.schre...@gmail.com>
Commit: Dominik Schrempf <dominik.schre...@gmail.com>
readme: fix typos, add some opinionated changes
fixes #12 and fixes #13
---
README.org | 108 ++++++++++++++++++++++++++++---------------------------------
1 file changed, 49 insertions(+), 59 deletions(-)
diff --git a/README.org b/README.org
index f2349da9ee..4cc715d748 100644
--- a/README.org
+++ b/README.org
@@ -3,69 +3,68 @@
* haskell-ts-mode
-A haskell mode that uses treesitter.
+A Haskell mode that uses
[[https://tree-sitter.github.io/tree-sitter/][Tree-sitter]].
* Screenshot
[[./ss.png]]
-The above screenshot is indented and coloured using haskell-ts-mode,
-with =prettify-symbols-mode= enabled.
+The above screenshot is indented and coloured using =haskell-ts-mode=, with
+=prettify-symbols-mode= enabled.
* Usage
-=C-c C-r= to open REPL
-=C-c C-c= to send code to repl
-=C-M-q= Indent the function
+- =C-c C-r= Open REPL
+- =C-c C-c= Send code to REPL
+- =C-M-q= Indent the function
* Features
-say it with me: indentation does not change the syntax-tree. This
-means that the indenation is a lot more predictable, but sometimes you
-must manually press M-i to indent.
+Say it with me: Indentation does not change the syntax tree. This means that
the
+indentation is a lot more predictable, but sometimes you must manually press
+=M-i= to indent.
-an overview of the features are:
-- Syntax highliting
+Overview of features:
+- Syntax highlighting
- Structural navigation
- Indentation
- Imenu support
-- REPL (C-c r in the mode to run)
-- Prettify symbols mode support
+- REPL (=C-c C-r= in the mode to run)
+- Prettify Symbols mode support
-* Comparasion with haskell-mode
+* Comparison with =haskell-mode=
The more interesting features are:
- Logical syntax highlighting:
- - Only arguments that can be used in functions are highlighted, eg
- in =f (_:(a:[]))= only =a= is highlighted, as it is the only
- variable that is captured that can be used in body of function
- - The return type of a function is highlighted
- - All new variabels are(or should be) highlighted, this includes
- generators, lambda args.
- - highlighting the '=' operaotr in guarded matches correctly, this
- would be stupidly hard in regexp based syntax
-- More perfomant, this is especially seen in longer files
-- Much much less code, haskell mode has accumlated 30,000 lines of
- features to do with all things haskell related, this mode just keeps
- the scope to basic major mode stuff, and leaves other stuff for
- external packages.
+ - Only arguments that can be used in functions are highlighted, e.g., in =f
+ (_:(a:[]))= only =a= is highlighted, as it is the only variable that is
+ captured, and that can be used in the body of the function.
+ - The return type of a function is highlighted.
+ - All new variabels are (or should be) highlighted, this includes generators,
+ lambda arguments.
+ - Highlighting the ~=~ operator in guarded matches correctly, this would be
+ stupidly hard in regexp based syntax.
+- More performant, this is especially seen in longer files.
+- Much, much less code, =haskell-mode= has accumlated 30,000 lines of code and
+ features to do with all things Haskell related. =haskell-ts-mode= just keeps
+ the scope to basic major mode stuff, and leaves other stuff to external
+ packages.
* Motivation
-=haskell-mode= contains nearly 30k lines of code, and is
-about 30 years old. Therefore, a lot of stuff emacs has gained the
-ability to do in those years, haskell-mode already has implemented
-them.
+=haskell-mode= contains nearly 30k lines of code, and is about 30 years old. A
+lot of features implemented by =haskell-mode= are now also available in
standard
+Emacs, and have thus become obsolete.
-In 2018, a mode called =haskell-tng-mode= was made to solve some of
-these problems. However because of haskell's syntax, it too became
-very complex and required a web of dependencies.
+In 2018, a mode called
[[https://elpa.nongnu.org/nongnu/haskell-tng-mode.html][=haskell-tng-mode=]]
was made to solve some of these
+problems. However, because of Haskell's syntax, it too became very complex and
+required a web of dependencies.
-Both these modes ended up practically parsing haskells syntax to
-implement indentation, so I thought why not use tree sitter?
+Both these modes ended up practically parsing Haskell's syntax to implement
+indentation, so I thought why not use Tree-sitter?
* Structural navigation
-This mode provides strucural navigation, for emacs 30+.
+This mode provides strucural navigation, for Emacs 30+.
#+begin_src haskell
combs (x:xs) = map (x:) c ++ c
@@ -73,14 +72,13 @@ This mode provides strucural navigation, for emacs 30+.
#+end_src
In the above code, if the pointer is right in front of the function
-defintion =combs=, and you do C-M-f (~forward-sexp~), it will take you to
+definition =combs=, and you press =C-M-f= (~forward-sexp~), it will take you to
the end of the second line.
-
* Installation
-The package is avaiable on elpa, you can install it using:
-M-x package-install RET haskell-ts-mode RET
+The package is avaiable on
[[https://elpa.nongnu.org/nongnu/haskell-ts-mode.html][NonGnu ELPA]], you can
install it using:
+: M-x package-install RET haskell-ts-mode RET
#+begin_src elisp
(add-to-list 'load-path "path/to/haskell-ts-mode")
@@ -89,22 +87,13 @@ M-x package-install RET haskell-ts-mode RET
* Customization
-If colour is too much or too less for you, adjust
-=treesit-font-lock-level= accordingly.
-
-If you want to highlight signature declarations (disabled by default),
-add the following to your init file:
-#+begin_src emacs-lisp
-(setq haskell-ts-highlight-signature t)
-#+end_src
-
-** how to disable haskell-ts-mode indentation
+** How to disable =haskell-ts-mode= indentation
#+begin_src emacs-lisp
(setq haskell-ts-use-indent nil)
#+end_src
-** Pretify symbols mode
+** Pretify Symbols mode
=prettify-symbols-mode= can be used to replace common symbols with
unicode alternatives.
@@ -113,14 +102,15 @@ unicode alternatives.
#+end_src
** Adjusting font lock level
-set =haskell-ts-font-lock-level= accordingly. Default value is 4, so if
+
+Set =haskell-ts-font-lock-level= accordingly. Default value is 4, so if
you suffer from contagious dehydration, you can lower it.
** Language server
-=haskell-ts-mode= now works with =lsp-mode=, however =lsp-haskell= still
requires on =haskell-mode=.
+=haskell-ts-mode= works with =lsp-mode=.
-To add =eglot= support, add the following code to you init.el:
+To add =eglot= support, add the following code to your =init.el=:
#+begin_src emacs-lisp
(with-eval-after-load 'eglot
@@ -130,9 +120,9 @@ To add =eglot= support, add the following code to you
init.el:
#+end_src
* TODO
-- Imenu support for functions with multiple definitions
-- _Proper indenting of multiline signatures_: the treesitter grammer
- does not flatten the signautes, rather leaves them to the standard
- infix interpretatoin. This makes indentation hard, as it will mean
+- Imenu support for functions with multiple definitions.
+- _Proper indenting of multiline signatures_: the Tree-sitter grammar
+ does not flatten the signatures, but rather leaves them to the standard
+ infix interpretation. This makes indentation hard, as it will mean
the only way to check if the the signature node is an ancestor of
node at point is to perfom a recursive ascent.
