@@ -289,7 +289,11 @@ Reader options
289289: Set the metadata field *KEY* to the value *VAL*. A value specified
290290 on the command line overrides a value specified in the document.
291291 Values will be parsed as YAML boolean or string values. If no value is
292− specified, the value will be treated as Boolean true.
292+ specified, the value will be treated as Boolean true. Like
293+ `--variable`, `--metadata` causes template variables to be set.
294+ But unlike `--variable`, `--metadata` affects the metadata of the
295+ underlying document (which is accessible from filters and may be
296+ printed in some output formats).
293297
294298`--normalize`
295299: Normalize the document after reading: merge adjacent