diff --git a/README b/README
index 6c9c9d3ed..ba1f93661 100644
--- a/README
+++ b/README
@@ -289,7 +289,11 @@ Reader options
 :   Set the metadata field *KEY* to the value *VAL*.  A value specified
     on the command line overrides a value specified in the document.
     Values will be parsed as YAML boolean or string values. If no value is
-    specified, the value will be treated as Boolean true.
+    specified, the value will be treated as Boolean true.  Like
+    `--variable`, `--metadata` causes template variables to be set.
+    But unlike `--variable`, `--metadata` affects the metadata of the
+    underlying document (which is accessible from filters and may be
+    printed in some output formats).
 
 `--normalize`
 :   Normalize the document after reading:  merge adjacent