From 419df111bf5b79ac7d370b3c83cc309fbb3700e7 Mon Sep 17 00:00:00 2001
From: Jeremie Dimino <jdimino@janestreet.com>
Date: Tue, 30 May 2017 17:10:50 +0100
Subject: [PATCH] Update doc

---
 doc/jbuild.rst | 38 ++++++++++++++++++++++++++------------
 1 file changed, 26 insertions(+), 12 deletions(-)

diff --git a/doc/jbuild.rst b/doc/jbuild.rst
index 4117a1ac..e86926ee 100644
--- a/doc/jbuild.rst
+++ b/doc/jbuild.rst
@@ -536,12 +536,10 @@ Jbuilder supports the following variables:
 
 In addition, ``(action ...)`` fields support the following special variables:
 
-- ``@`` expands to the list of target, separated by spaces
-- ``!@`` same as ``@`` but with a split semantic (see below)
+- ``@`` expands to the list of target
 - ``<`` expands to the first dependency, or the empty string if there are no
    dependencies
--  ``^`` expands to the list of dependencies, separated by spaces
-- ``!^`` same as ``^`` but with a split semantic (see below)
+-  ``^`` expands to the list of dependencies
 -  ``path:<path>`` expands to ``<path>``
 - ``exe:<path>`` is the same as ``<path>``, except when cross-compiling, in
    which case it will expand to ``<path>`` from the host build context
@@ -564,18 +562,37 @@ In addition, ``(action ...)`` fields support the following special variables:
    -  it is available locally and is not optional
    -  it is available locally and all its library dependencies are
       available
-
 -  ``version:<package>`` expands to the version of the given
    package. Note that this is only supported for packages that are
    being defined in the current scope
+-  ``read:<path>`` expands to the contents of the given file
+-  ``read-lines:<path>`` expands to the list of lines in the given
+   file
+-  ``read-strings:<path>`` expands to the list of lines in the given
+   file, unescaped using OCaml lexical convention
 
 The ``${<kind>:...}`` forms are what allows you to write custom rules that work
 transparently whether things are installed or not.
 
 Note that aliases are ignored by both ``${<}`` and ``${^}``.
 
-Moreover ``${^}`` and ``${@}`` will always expand to a single
-string. For instance in:
+The intent of this last form is to reliably read a list of strings
+generated by an OCaml program via:
+
+.. code:: ocaml
+
+    List.iter (fun s -> print_string (String.escaped s)) l
+
+#. Expansion of lists
+
+Forms that expands to list of items, such as ``${^}``, ``${@}`` or
+``${read-lines:...}`` will always expand to a single string where
+elements are separated by spaces. Inside ``(run <prog> <arguments>)``
+forms you can however split the items as several arguments by
+prefixing the variable with ``!``. Such forms can only be used as a
+whole atom, i.e. they can't be used inside a quoted atom.
+
+For instance in:
 
 .. code:: scheme
 
@@ -588,11 +605,8 @@ command will be equivalent to the shell command:
 
     $ foo "a b"
 
-In order to *split* them, you can use ``${!^}`` and ``${!@}``. These
-two forms are only available in ``(run ...)`` forms and can only be
-used as a whole atom, i.e. they can't be used inside a quoted
-atom. Replacing ``${^}`` by ``${!^}`` in the previous example would
-produce a command equivalent to this shell command:
+However, if you replace ``${^}`` by ``${!^}`` in the previous example
+the command produced would be equivalent to this shell command:
 
 .. code:: shell