docs: clarify the Python and CLI options for file variables

CHANGES.md

@@ -2,6 +2,7 @@
 
 ## python-markdown2 2.5.6 (not yet released)
 
+- [pull #736] Clarify how to enable file variables in the Python API and command-line help (#269, #365).
 - [pull #730] Fix `tables` extra splitting multi-backtick code spans at a leading pipe and merging cells after a code span containing literal backticks.
 - [pull #729] Fix `tables` extra merging cells when a pipe directly follows a code span, as in compact rows like `|`-v`|verbose|`.
 - [pull #725] Fix `tables` extra dropping escaped pipes at the end of header and body rows.

README.md

@@ -72,9 +72,10 @@ I think pip-based installation will enable this as well:
 $ markdown2 foo.md > foo.html
 ```
 
-Use `--use-file-vars` to enable extras declared in Emacs-style file variables,
-such as `<!-- -*- markdown-extras: header-ids -*- -->` at the top of a file.
-This flag takes no value; file variables are ignored by default.
+Use `--use-file-vars` on the CLI, or `use_file_vars=True` with `markdown()`,
+`markdown_path()` or `Markdown()`, to enable extras declared in Emacs-style
+file variables such as `<!-- -*- markdown-extras: header-ids -*- -->` at the top
+of a file. This option is disabled by default and is not an extra.
 
 ```shell
 $ markdown2 --use-file-vars foo.md > foo.html

lib/markdown2.py

@@ -98,8 +98,6 @@
   PHP-Markdown Extra <https://michelf.ca/projects/php-markdown/extra/#table>.
 * toc: The returned HTML string gets a new "toc_html" attribute which is
   a Table of Contents for the document. (experimental)
-* use-file-vars: Look for an Emacs-style markdown-extras file variable to turn
-  on Extras.
 * wiki-links: Wiki-style `[[Page Name]]` links. The generated URL and CSS class
   can be configured via the "base_url", "end_url", "html_class" and "build_url"
   options.