Update docs on directory targets (#5056)

During a discussion in #5025, we changed syntax from [output/*]
to [(dir output)] but I forgot to update the docs. 

This PR does that, and also cleans up a bit a related part in
the [hacking.rst].

Signed-off-by: Andrey Mokhov <[email protected]>

doc/dune-files.rst

@@ -986,10 +986,18 @@ or exactly one filename (if defined with ``target``). Note that at this time,
 Dune officially only supports user rules with targets in the current directory.
 However, starting from Dune 3.0, we provide an experimental support for
 *directory targets*, where an action can produce a whole tree of build
-artifacts. To specify a directory target, you can use the ``<dirname>/*``
-syntax, i.e., a directory name followed by a forward slash and a star. To
-enable this experimental feature, add ``(using directory-targets 0.1)`` to
-your ``dune-project`` file.
+artifacts. To specify a directory target, you can use the ``(dir <dirname>)``
+syntax. For example, the following stanza describes a rule with a file
+target ``foo`` and a directory target ``bar``.
+
+.. code:: scheme
+
+    (rule
+     (targets foo (dir bar))
+     (action  <action>))
+
+To enable this experimental feature, add ``(using directory-targets 0.1)``
+to your ``dune-project`` file.
 
 
 ``<action>`` is what you run to produce the targets from the dependencies.

doc/hacking.rst

@@ -188,24 +188,24 @@ Dune Rules
 Creating Rules
 --------------
 
-A dune rule consists of 3 components:
+A Dune rule consists of 3 components:
 
-- Dependencies that the rule may read when executed (files, aliases, ..)
-  This is described by ``'a Action_builder.t`` values
+- *Dependencies* that the rule may read when executed (files, aliases, etc.).
+  This is described by ``'a Action_builder.t`` values.
 
-- Targets the rule produces (files)
-  Targets, in addition to dependencies is described by ``'a Action_builder.With_targets.t'``
+- *Targets* that the rule produces (files and/or directories).
+  This is described by ``'a Action_builder.With_targets.t'`` values.
 
-- Action that dune must execute (external programs, redirects, etc.)
-  Actions are represented by ``Action.t``
+- *Action* that Dune must execute (external programs, redirects, etc.).
+  Actions are represented by ``Action.t`` values.
 
-Combined, one needs to produce a ``Action.t Action_builder.With_targets.t`` value to
-create a rule. The rule may then be added by ``Super_context.add_rule``, or a
-related function.
+Combined, one needs to produce an ``Action.t Action_builder.With_targets.t``
+value to create a rule. The rule may then be added by
+``Super_context.add_rule``, or a related function.
 
 To make this maximally convenient, there's a ``Command`` module to make it
-easier to create actions that run external commands and describe their targets &
-dependencies simultaneously.
+easier to create actions that run external commands and describe their targets
+and dependencies simultaneously.
 
 Loading Rules
 -------------