2 files changed, 67 insertions, 3 deletions
diff --git a/docs/markdown/Syntax.md b/docs/markdown/Syntax.md
index 22b8be3..9ea96c1 100644
--- a/docs/markdown/Syntax.md
+++ b/docs/markdown/Syntax.md
@@ -138,9 +138,9 @@ int main (int argc, char ** argv) {
 }'''
 ```
 
-These are raw strings that do not support the escape sequences listed above.
-These strings can also be combined with the string formatting functionality
-described below.
+These are raw strings that do not support the escape sequences listed
+above.  These strings can also be combined with the string formatting
+functionality described below.
 
 #### String formatting
 
@@ -351,6 +351,42 @@ creating build objects.
 executable('progname', 'prog.c')
 ```
 
+Most functions take only few positional arguments but several keyword
+arguments, which are specified like this:
+
+```meson
+executable('progname',
+  sources: 'prog.c',
+  c_args: '-DFOO=1')
+```
+
+Starting with version 0.49.0 keyword arguments can be specified
+dynamically. This is done by passing dictionary representing the
+keywords to set in the `kwargs` keyword. The previous example would be
+specified like this:
+
+```meson
+d = {'sources': 'prog.c',
+  'c_args': '-DFOO=1'}
+
+executable('progname',
+  kwargs: d)
+```
+
+A single function can take keyword argumets both directly in the
+function call and indirectly via the `kwargs` keyword argument. The
+only limitation is that it is a hard error to pass any particular key
+both as a direct and indirect argument.
+
+```meson
+d = {'c_args': '-DFOO'}
+executable('progname', 'prog.c',
+  c_args: '-DBAZ=1',
+  kwargs: d) # This is an error!
+```
+
+Attempting to do this causes Meson to immediately exit with an error.
+
 Method calls
 --
 
diff --git a/docs/markdown/snippets/kwargdict.md b/docs/markdown/snippets/kwargdict.md
new file mode 100644
index 0000000..47c54d5
--- /dev/null
+++ b/docs/markdown/snippets/kwargdict.md
@@ -0,0 +1,28 @@
+## Can specify keyword arguments with a dictionary
+
+You can now specify keyword arguments for any function and method call
+with the `kwargs` keyword argument. This is perhaps best described
+with an example.
+
+```meson
+options = {'include_directories': include_directories('inc')}
+
+...
+
+executable(...
+  kwargs: options)
+```
+
+The above code is identical to this:
+
+```meson
+executable(...
+  include_directories: include_directories('inc'))
+```
+
+That is, Mesn will expand the dictionary given to `kwargs` as if the
+entries in it had been given as keyword arguments directly.
+
+Note that any individual argument can be specified either directly or
+with the `kwarg`` dict but not both. If a key is specified twice, it
+is a hard error.