merge: rewrite-docs
I've omitted docs/*.org from this merge, as there is still work left to do there, but I am pushing the module docs early so folks can benefit from the new docs sooner.
This commit is contained in:
Henrik Lissner
commit
1f8bf7accb
179 changed files with 13125 additions and 8630 deletions
|
|
@ -1,93 +1,115 @@
|
|||
#+TITLE: lang/ocaml
|
||||
#+DATE: June 27, 2017
|
||||
#+SINCE: v2.0.3
|
||||
# -*- mode: doom-docs-org -*-
|
||||
#+title: :lang ocaml
|
||||
#+subtitle: An objective camel
|
||||
#+created: June 27, 2017
|
||||
#+since: 2.0.4 (#128)
|
||||
|
||||
* Table of Contents :TOC:
|
||||
- [[#description][Description]]
|
||||
- [[#module-flags][Module Flags]]
|
||||
- [[#plugins][Plugins]]
|
||||
- [[#prerequisites][Prerequisites]]
|
||||
- [[#features][Features]]
|
||||
- [[#configuration][Configuration]]
|
||||
- [[#appendix][Appendix]]
|
||||
- [[#commands][Commands]]
|
||||
- [[#hacks][Hacks]]
|
||||
* Description :unfold:
|
||||
This module adds [[https://ocaml.org/][OCaml]] support to Doom Emacs, powered by [[doom-package:][tuareg-mode]].
|
||||
|
||||
* Description
|
||||
This module adds [[https://ocaml.org/][OCaml]] support to Doom Emacs, powered by [[https://github.com/ocaml/tuareg][tuareg-mode]].
|
||||
- Code completion, documentation look-up, code navigation and refactoring
|
||||
([[doom-package:][merlin]])
|
||||
- Type, documentation and function argument display on idle ([[doom-package:][merlin-eldoc]])
|
||||
- REPL ([[doom-package:][utop]])
|
||||
- Syntax-checking ([[doom-package:][merlin]] with [[doom-package:][flycheck-ocaml]])
|
||||
- Auto-indentation ([[doom-package:][ocp-indent]])
|
||||
- Code formatting ([[doom-package:][ocamlformat]])
|
||||
- Dune file format ([[doom-package:][dune]])
|
||||
|
||||
+ Code completion, documentation look-up, code navigation and refactoring
|
||||
([[https://github.com/ocaml/merlin/wiki/emacs-from-scratch][merlin]])
|
||||
+ Type, documentation and function argument display on idle ([[https://github.com/Khady/merlin-eldoc][merlin-eldoc]])
|
||||
+ 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]])
|
||||
** Maintainers
|
||||
*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]]
|
||||
|
||||
** Module Flags
|
||||
This module provides no flags.
|
||||
** Module flags
|
||||
- +lsp ::
|
||||
Enable LSP support for ~tuareg-mode~. Requires [[doom-module:][:tools lsp]] and a langserver
|
||||
(supports [[https://github.com/freebroccolo/ocaml-language-server][ocaml-language-server]]).
|
||||
- +tree-sitter ::
|
||||
Leverages tree-sitter for better syntax highlighting and structural text
|
||||
editing. Requires [[doom-module:][:tools tree-sitter]].
|
||||
|
||||
** Plugins
|
||||
+ [[https://github.com/ocaml/tuareg][tuareg]]
|
||||
+ [[https://github.com/ocaml/merlin][merlin]]
|
||||
+ [[https://github.com/Khady/merlin-eldoc][merlin-eldoc]]
|
||||
+ [[https://github.com/OCamlPro/ocp-indent][ocp-indent]]
|
||||
+ [[https://github.com/flycheck/flycheck-ocaml][flycheck-ocaml]]*
|
||||
+ [[https://github.com/ocaml-community/utop][utop]]*
|
||||
+ [[https://github.com/ocaml-ppx/ocamlformat][ocamlformat]]*
|
||||
+ [[https://github.com/ocaml/dune][dune]]
|
||||
|
||||
* Prerequisites
|
||||
This module has no hard dependencies, but it is recommanded that you install
|
||||
[[http://opam.ocaml.org/][opam]] and the following opam (optional) packages:
|
||||
|
||||
#+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=, if it is available.
|
||||
|
||||
* Configuration
|
||||
+ If =:completion company= is enabled then autocomplete is provided by =merlin=
|
||||
+ When =:checkers syntax= 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 =:checkers spell= is active
|
||||
+ A REPL is provided if =utop= is installed and =:tools eval= is active
|
||||
+ 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=
|
||||
+ If =:editor multiple-cursors= is enabled then identifiers can be refactored
|
||||
with =v R= and multiple cursors (this correctly matches identifier occurrences
|
||||
according to scope, it is not purely a textual match)
|
||||
+ If =:emacs imenu= is enabled then top level symbols (modules, type, functions,
|
||||
etc.) can be looked up using =SPC / i=
|
||||
|
||||
Run =doom sync= to install all packages and =doom doctor= to diagnose missing
|
||||
tools.
|
||||
|
||||
* Appendix
|
||||
** Commands
|
||||
| Command | Key | Description |
|
||||
|------------------------------+-------------------+-----------------------------------------------------------|
|
||||
| =merlin-type-enclosing= | =<localleader> t= | display type under point |
|
||||
| =tuareg-find-alternate-file= | =<localleader> a= | switch between =.ml= and =.mli= |
|
||||
| =merlin-locate= | =g d= | lookup definition |
|
||||
| =merlin-occurences= | =SPC c D= | lookup references |
|
||||
| =merlin-document= | =K= | lookup documentation |
|
||||
| =merlin-imenu= | =SPC s i= | symbol lookup in file |
|
||||
| =merlin-iedit-occurrences= | =v R= | visual refactor identifier under point (multiple cursors) |
|
||||
| =utop= | =SPC o r= | open =utop= as REPL |
|
||||
| =utop-eval-region= | =SPC c e= | evaluate selected region in =utop= |
|
||||
** Packages
|
||||
- [[doom-package:][dune]]
|
||||
- [[doom-package:][ocamlformat]] if [[doom-module:][:editor format]]
|
||||
- [[doom-package:][ocp-indent]]
|
||||
- [[doom-package:][tuareg]]
|
||||
- [[doom-package:][utop]] if [[doom-module:][:tools eval]]
|
||||
- unless [[doom-module:][+lsp]]
|
||||
- [[doom-package:][flycheck-ocaml]] if [[doom-module:][:checkers syntax]]
|
||||
- [[doom-package:][merlin]]
|
||||
- [[doom-package:][merlin-company]]
|
||||
- [[doom-package:][merlin-eldoc]]
|
||||
|
||||
** Hacks
|
||||
+ =set-ligatures!= 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
|
||||
- ~set-ligatures!~ 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 [[doom-package:][tuareg]] is loaded
|
||||
|
||||
** TODO Changelog
|
||||
# This section will be machine generated. Don't edit it by hand.
|
||||
/This module does not have a changelog yet./
|
||||
|
||||
* Installation
|
||||
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
|
||||
|
||||
This module requires the following packages available through [[http://opam.ocaml.org/][opam]]:
|
||||
- merlin
|
||||
- utop
|
||||
- ocp-indent
|
||||
- dune
|
||||
- ocamlformat
|
||||
|
||||
* TODO Usage
|
||||
#+begin_quote
|
||||
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
|
||||
#+end_quote
|
||||
|
||||
- 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=, if it is available.
|
||||
|
||||
| Command | Key | Description |
|
||||
|------------------------------+-----------------+-----------------------------------------------------------|
|
||||
| ~merlin-type-enclosing~ | [[kbd:][<localleader> t]] | display type under point |
|
||||
| ~tuareg-find-alternate-file~ | [[kbd:][<localleader> a]] | switch between =.ml= and =.mli= |
|
||||
| ~merlin-locate~ | [[kbd:][g d]] | lookup definition |
|
||||
| ~merlin-occurences~ | [[kbd:][SPC c D]] | lookup references |
|
||||
| ~merlin-document~ | [[kbd:][K]] | lookup documentation |
|
||||
| ~merlin-imenu~ | [[kbd:][SPC s i]] | symbol lookup in file |
|
||||
| ~merlin-iedit-occurrences~ | [[kbd:][v R]] | visual refactor identifier under point (multiple cursors) |
|
||||
| ~utop~ | [[kbd:][SPC o r]] | open =utop= as REPL |
|
||||
| ~utop-eval-region~ | [[kbd:][SPC c e]] | evaluate selected region in =utop= |
|
||||
|
||||
* TODO Configuration
|
||||
#+begin_quote
|
||||
🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
|
||||
#+end_quote
|
||||
|
||||
- If [[doom-module:][:completion company]] is enabled then autocomplete is provided by [[doom-package:][merlin]]
|
||||
- When [[doom-module:][:checkers syntax]] is enabled then [[doom-package:][flycheck-ocaml]] is activated to do
|
||||
on-the-fly syntax/type checking via [[doom-package:][merlin]], otherwise this is only done when
|
||||
the file is saved.
|
||||
- Spell checking is activated in comments if [[doom-module:][:checkers spell]] is active
|
||||
- A REPL is provided if [[doom-package:][utop]] is installed and [[doom-module:][:tools eval]] is active
|
||||
- If [[doom-module:][: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=
|
||||
- If [[doom-module:][:editor multiple-cursors]] is enabled then identifiers can be refactored with
|
||||
[[kbd:][v R]] and multiple cursors (this correctly matches identifier occurrences
|
||||
according to scope, it is not purely a textual match)
|
||||
|
||||
Run ~$ doom sync~ to install all packages and ~$ doom doctor~ to diagnose
|
||||
missing tools.
|
||||
|
||||
* Troubleshooting
|
||||
/There are no known problems with this module./ [[doom-report:][Report one?]]
|
||||
|
||||
* Frequently asked questions
|
||||
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
|
||||
|
||||
* TODO Appendix
|
||||
#+begin_quote
|
||||
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
|
||||
#+end_quote
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue