Added `--extension_configs` option to the CLI.

The `--extension_configs` option must point to a YAML or JSON file.
The contents of the file must parse to a Python Dict which will be
passed to the `extension_configs` keyword of the `markdown.Markdown`
class.

Also added tests for all of the CLI option parsing options and updated
documentation.

1 files changed, 52 insertions, 6 deletions

diff --git a/docs/cli.txt b/docs/cli.txt
index ff19501..f805b5e 100644
--- a/docs/cli.txt
+++ b/docs/cli.txt
@@ -112,13 +112,59 @@ For a complete list of options, run
 Using Extensions
 ----------------
 
-For an extension to be run from the command line it must be provided in a module
-on your python path (see the [Extension API](extensions/api.html) for details).
-It can then be invoked by the name of that module:
+To load a Python-Markdown extension from the command line use the `-x` 
+(or `--extension`) option. For extensions included with Python-Markdown, use 
+the short "Name" [documented] for that extension. 
 
-    $ markdown_py -x footnotes text_with_footnotes.txt > output.html
+[documented]: index.html#officially-supported-extensions
 
-If the extension supports config options, you can pass them in as well:
+    $ python -m markdown -x footnotes text_with_footnotes.txt
 
-    $ markdown_py -x "footnotes(PLACE_MARKER=~~~~~~~~)" input.txt
+For third party extensions, the extension module must be on your `PYTHONPATH` 
+(see the [Extension API](extensions/api.html) for details). The extension can 
+then be invoked by the name of that module using Python's dot syntax:
+
+	$ python -m markdown -x path.to.module input.txt
+
+To load multiple extensions, specify an `-x` option for each extension:
+
+	$ python -m markdown -x footnotes -x codehilite input.txt
+
+If the extension supports configuration options (see the documentation for the 
+extension you are using to determine what settings it supports, if any), you 
+can pass them in as well:
+
+	$ python -m markdown -x footnotes -c config.yml input.txt
+
+The `-c` (or `--extension_configs`) option accepts a file name. The file must be in
+either the [YAML] or [JSON] format and contain YAML or JSON data that would map to
+a Python Dictionary in the format required by the [`extension_configs`][ec] keyword 
+of the `markdown.Markdown` class. Therefore, the file `config.yaml` referenced in the 
+above example might look like this:
+
+	footnotes:
+		PLACE_MARKER: ~~~~~~~~
+		UNIQUE_IDS: True
+
+Note that while the `--extension_configs` option does specify the "footnotes" extension,
+you still need to load the extension with the `-x` option, or the configs for that
+extension will be ignored.
+
+The `--extension_configs` option will only support YAML config files if [PyYaml] is
+installed on your system. JSON should work with no additional dependencies. The format
+of your config file is automatically detected.
+
+As an alternative, you may append the extension configs as a string to the extension name 
+that is provided to the `-x-` option in the following format:
+
+	$ python -m markdown -x "footnotes(PLACE_MARKER=~~~~~~~~,UNIQUE_IDS=1)" input.txt
+
+Note that there are no quotes or whitespace in the above format, which severely limits 
+how it can be used. For more complex settings, it is suggested that the 
+`--extension_configs` option be used.
+
+[ec]: reference.html#extension_configs
+[YAML]: http://yaml.org/
+[JSON]: http://json.org/
+[PyYAML]: http://pyyaml.org/