Improve ocaml language support

See README.org.

Signed-off-by: Edwin Török <edwin@etorok.net>

modules/lang/ocaml/README.org

@@ -0,0 +1,79 @@
+#+TITLE: :lang ocaml
+
+This module adds  [[https://ocaml.org/][OCaml]] support, powered by [[https://github.com/ocaml/tuareg][tuareg-mode]].
+
++ Code completion, look up documentation, and code navigation ([[https://github.com/ocaml/merlin/wiki/emacs-from-scratch][merlin]])
++ REPL ([[https://github.com/ocaml-community/utop][utop]])
++ Syntax-checking (~merlin~ with [[https://github.com/flycheck/flycheck-ocaml][flycheck-ocaml]])
++ Auto-indentation ([[https://github.com/OCamlPro/ocp-indent][ocp-indent]])
++ Code formatting ([[https://github.com/ocaml-ppx/ocamlformat][ocamlformat]])
++ Dune file format ([[http://dune.build/][dune]])
+
+* Table of Contents :TOC:
+- [[Module Flags][Module Flags]]
+- [[Prerequisites][Prerequisites]]
+- [[Features][Features]]
+- [[Configuration][Configuration]]
+- [[Appendix][Appendix]]
+  - [[Commands][Commands]]
+  - [[Hacks][Hacks]]
+
+* Module Flags
+This module provides the ~+opam-site-lisp~ flag to compile editor support ~.el~
+files from  opam's =site-lisp= directory.
+By default all editor plugins are installed from MELPA/GitHub even if the
+corresponding =opam= package isn't installed.
+If this flag is enabled then you must have all of the packages listed in
+=package.el= installed via =opam=.
+
+To enable this, use:
+#+BEGIN_SRC emacs-lisp
+(doom! :lang (ocaml +opam-site-lisp))
+#+END_SRC
+
+* Prerequisites
+It is highly recommended to install [[http://opam.ocaml.org/][opam]].
+To get all the features you should also install these ~opam~ packages, however
+they are not all required (features should be disabled gracefully when a tool is
+missing):
+#+BEGIN_SRC shell
+opam install merlin utop ocp-indent dune ocamlformat
+#+END_SRC
+
+* Features
++ the following files should have syntax highlighting support:
+~.ml{i,p,y,}~, ~.eliom{i,}~,  ~jbuild~, ~dune~, ~opam~
++ =merlin-mode= is activated whenever a =.merlin= file is found (including in a
+  parent directory) and =ocamlmerlin= executable is present
++ line-based auto-indentation is provided by =ocp-indent= when installed
+
+* Configuration
++ if =:completion company= is enabled then autocomplete is provided by =merlin=
++ when =:feature syntax-checker= is enabled then =flycheck-ocaml= is activated
+  to do on-the-fly syntax/type checking via =merlin=, otherwise this is only
+  done when the file is saved.
++ spell checking is activated in comments if =:feature spellcheck= is actived
++ a REPL is provided if =utop= is installed and =:feature eval= is actived
++ if =:editor format= is enabled, the =ocamlformat= executable is available and
+  there is an =.ocamlformat= file present then =format-all-buffer= is bound to
+  =ocamlformat=, otherwise to =ocp-indent=
+
+Run =make install= to install all packages, and =make doctor= to diagnose missing tools.
+
+* Appendix
+** Commands
+  | command                      | key / ex command | description                        |
+  |------------------------------+------------------+------------------------------------|
+  | =merlin-type-enclosing=      | =SPC m t=        | display type under point           |
+  | =tuareg-find-alternate-file= | =SPC m a=        | switch between =.ml= and =.mli=    |
+  | =merlin-locate=              | =gd=             | lookup definition                  |
+  | =merlin-occurences=          | =SPC c D=        | lookup references                  |
+  | =merlin-document=            | =K=              | lookup documentation               |
+  | =utop=                       | =SPC o r=        | open =utop= as REPL                |
+  | =utop-eval-region=           | =SPC c e=        | evaluate selected region in =utop= |
+
+** Hacks
++ =set-pretty-symbols!= is called with the full tuareg prettify symbol list, this
+  can cause columns to change as certain keywords are shortened (e.g. =fun=
+  becomes \lambda.
++ =tuareg-opam-update-env= is called the first time =tuareg= is loaded