From 8a3aac990e4fa5ee9d235b9880cded1c7159964e Mon Sep 17 00:00:00 2001
From: Marc Chevrier <marc.chevrier@gmail.com>
Date: Sat, 8 Jan 2022 12:04:27 +0100
Subject: Help: add_custom_command: describes depfile format

---
 Help/command/add_custom_command.rst | 45 ++++++++++++++++++++++++++++++++++---
 1 file changed, 42 insertions(+), 3 deletions(-)

diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst
index b45a079..f07b4a6 100644
--- a/Help/command/add_custom_command.rst
+++ b/Help/command/add_custom_command.rst
@@ -271,9 +271,48 @@ The options are:
 ``DEPFILE``
   .. versionadded:: 3.7
 
-  Specify a ``.d`` depfile which holds dependencies for the custom command.
-  It is usually emitted by the custom command itself.  This keyword may only
-  be used if the generator supports it, as detailed below.
+  Specify a depfile which holds dependencies for the custom command. It is
+  usually emitted by the custom command itself.  This keyword may only be used
+  if the generator supports it, as detailed below.
+
+  The expected format, compatible with what is generated by ``gcc`` with the
+  option ``-M``, is independent of the generator or platform.
+
+  The formal syntax, as specified using
+  `BNF <https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form>`_ notation with
+  the regular extensions, is the following:
+
+  .. raw:: latex
+
+    \begin{small}
+
+  .. productionlist:: depfile
+    depfile: `rule`*
+    rule: `targets` (`colon` `dependencies`?)? `eol`
+    colon: `separator`* ':' space `separator`*
+    targets: `target` (`separator` `target`)*
+    target: `pathname`
+    dependencies: `dependency` (`separator` `dependency`)*
+    dependency: `pathname`
+    separator: (space | line_continue)+
+    line_continue: '\' `eol`
+    space: ' ' | '\t'
+    pathname: `character`+
+    character: `std_character` | `dollar` | `hash` | `whitespace`
+    std_character: <any character except '$', '#' or ' '>
+    dollar: '$$'
+    hash: '\#'
+    whitespace: '\ '
+    eol: '\r'? '\n'
+
+  .. raw:: latex
+
+    \end{small}
+
+  .. note::
+
+    As part of ``pathname``, any slash and backslash is interpreted as
+    a directory separator.
 
   .. versionadded:: 3.7
     The :generator:`Ninja` generator supports ``DEPFILE`` since the keyword
-- 
cgit v0.12