From 8b81f79444a59e5a6ae4fe4abcb0fdd35a19f140 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Nicol=C3=A1s=20Ojeda=20B=C3=A4r?= <n.oje.bar@gmail.com>
Date: Sun, 6 Oct 2019 21:07:57 +0200
Subject: [PATCH] Add documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Nicolás Ojeda Bär <n.oje.bar@gmail.com>
---
 doc/concepts.rst   | 27 +++++++++++++++++++++++++++
 doc/dune-files.rst | 10 +++++-----
 2 files changed, 32 insertions(+), 5 deletions(-)

diff --git a/doc/concepts.rst b/doc/concepts.rst
index 87c660cff8ce..6a7b52b94260 100755
--- a/doc/concepts.rst
+++ b/doc/concepts.rst
@@ -87,6 +87,29 @@ an flambda compiler with the help of variable expansion:
 
    (and %{ocamlc-config:flambda} (= %{ocamlc-config:system} macosx))
 
+.. _predicate-lang:
+
+Predicate language
+==================
+
+The predicate language allows the user to define simple predicates
+(boolean-valued functions) that dune can evaluate. Here is a semi formal
+specification of the language:
+
+.. code::
+
+   pred := (and <pred> <pred>)
+         | (or <pred> <pred>
+         | (not <pred>)
+         | :standard
+         | <element>+
+
+The exact meaning of ``:standard`` and the nature of ``<element>`` depends on
+the context. For example, in the case of the :ref:`dune-subdirs`, an
+``<element>`` corresponds to file glob patterns. Another example is the user
+action :ref:`(with-exit-codes ...) <user-actions>`, where an ``<element>``
+corresponds to a literal integer.
+
 .. _variables:
 
 Variables
@@ -620,6 +643,10 @@ The following constructions are available:
 - ``(ignore-<outputs> <DSL)`` to ignore the output, where
   ``<outputs>`` is one of: ``stdout``, ``stderr`` or ``outputs``
 - ``(with-stdin-from <file> <DSL>)`` to redirect the input from a file
+- ``(with-exit-codes <pred> <DSL>)`` specifies the list of expected exit codes
+  for the programs executed in ``<DSL>``. ``<pred>`` is a predicate on integer
+  values, and is specified using the :ref:`predicate-lang`. This action is
+  available since dune 2.0.
 - ``(progn <DSL>...)`` to execute several commands in sequence
 - ``(echo <string>)`` to output a string on stdout
 - ``(write-file <file> <string>)`` writes ``<string>`` to ``<file>``
diff --git a/doc/dune-files.rst b/doc/dune-files.rst
index 15cdf2d295b6..8a6c0d68b337 100644
--- a/doc/dune-files.rst
+++ b/doc/dune-files.rst
@@ -804,10 +804,10 @@ field. The following modes are available:
     from the source tree.
   - ``(into <dir>)`` means that the files are promoted in ``<dir>`` instead of
     the current directory. This feature is available since Dune 1.8.
-  - ``(only <predicate>)`` means that only a subset of the targets
-    should be promoted. The argument is a predicate in a syntax
-    similar to the argument of :ref:`(dirs ...) <dune-subdirs>`. This
-    feature is available since dune 1.10.
+  - ``(only <predicate>)`` means that only a subset of the targets should be
+    promoted. The argument is similar to the argument of :ref:`(dirs ...)
+    <dune-subdirs>`, specified using the :ref:`predicate-lang`. This feature is
+    available since dune 1.10.
 
 - ``promote-until-clean`` is the same as ``(promote (until-clean))``
 - ``(promote-into <dir>)`` is the same as ``(promote (into <dir>))``
@@ -1275,7 +1275,7 @@ dirs (since 1.6)
 -------------------
 
 The ``dirs`` stanza allows to tell specify the sub-directories dune will
-include in a build. The syntax is based on dune's predicate language and allows
+include in a build. The syntax is based on dune's :ref:`predicate-lang` and allows
 the user the following operations:
 
 - The special value ``:standard`` which refers to the default set of used