Add manual doc

Signed-off-by: Nicolás Ojeda Bär <n.oje.bar@gmail.com>

doc/dialects.rst

@@ -0,0 +1,65 @@
+.. _dialects-main:
+
+********
+Dialects
+********
+
+A dialect is an alternative frontend to OCaml (such as ReasonML). It is
+described by a pair of file extensions, one corresponding to interfaces and one
+to implementations.
+
+The extensions are unique among all dialects of a given project, so that a given
+extension can be mapped back to the corresponding dialect.
+
+A dialect can use the standard OCaml syntax or it can specify an action to
+convert from a custom syntax to a binary OCaml abstract syntax tree.
+
+Similarly, a dialect can specify a custom formatter to implement the ``@fmt``
+alias, see :ref:`formatting-main`.
+
+When not using a custom syntax or formatting action, a dialect is nothing but a
+way to specify custom file extensions for OCaml code.
+
+Defining a dialect
+==================
+
+A dialect can be defined by adding the following to the ``dune-project`` file:
+
+.. code::
+
+    (dialect
+     (name <name>)
+     (implementation
+      (extension <string>)
+      <optional fields>)
+     (interface
+      (extension <string>)
+      <optional fields>))
+
+``<name>`` is the name of the dialect being defined. It must be unique in a
+given project.
+
+``(extension <string>)`` specifies the file extension used for this dialect, for
+interfaces and implementations. The extension string must not contain any dots,
+and be unique in a given project.
+
+``<optional fields>`` are:
+
+- ``(preprocess <action>)`` is the action to run to produce a valid OCaml
+  abstract syntax tree. It is expected to read the file given in the variable
+  named ``input-file`` and output a *binary* abstract syntax tree on its
+  standard output. See :ref:`preprocessing-actions` for more information.
+
+  If the field is not present, it is assumed that the corresponding source code
+  is already valid OCaml code and can be passed to the OCaml compiler as-is.
+
+
+- ``(format <action>)`` is the action to run to format source code for this
+  dialect. The action is expected to read the file given in the variable named
+  ``input-file`` and output the formatted source code on its standard
+  output. For more information. See :ref:`formatting-main` for more information.
+
+  If the field is not present, then if ``(preprocess <action>)`` is not present
+  (so that the dialect consists of valid OCaml code), then by default the
+  dialect will be formatted as any other OCaml code. Otherwise no special
+  formatting will be done.

doc/dune-files.rst

@@ -1307,6 +1307,8 @@ instance. When using such ppx rewriters, you must use ``staged_pps``
 instead of ``pps`` in order to force Dune to use the second pipeline,
 which is slower but necessary in this case.
 
+.. _preprocessing-actions:
+
 Preprocessing with actions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 

doc/formatting.rst

@@ -9,6 +9,9 @@ Dune can be set up to run automatic formatters for source code.
 It can use ocamlformat_ to format OCaml source code (``*.ml`` and ``*.mli``
 files) and refmt_ to format Reason source code (``*.re`` and ``*.rei`` files).
 
+Furthermore it can be used to format code of any defined dialect (see
+:ref:`dialects-main`).
+
 .. _ocamlformat: https://github.com/ocaml-ppx/ocamlformat
 .. _refmt: https://github.com/facebook/reason/tree/master/src/refmt
 
@@ -19,7 +22,7 @@ This feature is enabled by adding the following to the ``dune-project`` file:
 
 .. code:: scheme
 
-    (using fmt 1.1)
+    (using fmt 1.2)
 
 Formatting a project
 ====================
@@ -53,21 +56,26 @@ As usual with promotion, it is possible to combine these two steps by running
 Only enabling it for certain languages
 ======================================
 
-By default, formatting will be enabled for all languages present in the project
-that dune knows about. This is not always desirable, for example if in a mixed
-Reason/OCaml project, one only wants to format the Reason files to avoid pulling
-``ocamlformat`` as a dependency.
+By default, formatting will be enabled for all languages and dialects present in
+the project that dune knows about. This is not always desirable, for example if
+in a mixed Reason/OCaml project, one only wants to format the Reason files to
+avoid pulling ``ocamlformat`` as a dependency.
 
 In these cases, it is possible to use the ``enabled_for`` argument to restrict
 the languages that are considered for formatting.
 
 .. code:: scheme
 
-    (using fmt 1.1 (enabled_for reason))
+    (using fmt 1.2 (enabled_for reason))
 
 Version history
 ===============
 
+1.2
+---
+
+* Format :ref:`dialects-main`.
+
 1.1
 ---
 

doc/index.rst

@@ -26,6 +26,7 @@ Welcome to dune's documentation!
    jsoo
    opam
    variants
+   dialects
    formatting
    coq
    faq