docs: improved documentation of the extra/ extensions

Simplified, unified style, added some undocumented options.

NOTE: Footnotes/UNIQUE_IDS stays mostly undocumented

7 files changed, 74 insertions, 78 deletions

diff --git a/docs/extensions/abbreviations.txt b/docs/extensions/abbreviations.txt
index 21d90bf..e4c62f6 100644
--- a/docs/extensions/abbreviations.txt
+++ b/docs/extensions/abbreviations.txt
@@ -10,7 +10,7 @@ Abbreviations
 Summary
 -------
 
-The Markdown Abbreviation Extension adds the ability to define abbreviations. 
+The Abbreviation Extension adds the ability to define abbreviations. 
 Specifically, any defined abbreviation is wrapped in  an `<abbr>` tag.
 
 The Abbreviation extension is included in the standard Markdown library.
@@ -31,7 +31,7 @@ Thus, the following text (taken from the above referenced PHP documentation):
     *[HTML]: Hyper Text Markup Language
     *[W3C]:  World Wide Web Consortium
 
-will be rendered like so:
+will be rendered as:
 
     <p>The <abbr title="Hyper Text Markup Language">HTML</abbr> specification 
     is maintained by the <abbr title="World Wide Web Consortium">W3C</abbr>.</p>
@@ -39,21 +39,7 @@ will be rendered like so:
 Usage
 -----
 
-From the Python interpreter:
+See [Extensions](./index.html) for general extension usage, specify `abbr`
+as the name of the extension.
 
-    >>> import markdown
-    >>> text = """
-    ... Some text with an ABBR.
-    ...
-    ... *[ABBR]: Abbreviation
-    ... """
-    >>> html = markdown.markdown(text, ['abbr'])
-
-To use with other extensions, just add them to the list, like this:
-
-    >>> html = markdown.markdown(text, ['abbr', 'footnotes'])
-
-Abbreviations can also be called from the command line using Markdown's `-x` 
-parameter, like so:
-
-    python -m markdown -x abbr source.txt > output.html
+This extension does not accept any special configuration options.
diff --git a/docs/extensions/attr_list.txt b/docs/extensions/attr_list.txt
index 54a61d0..1af1510 100644
--- a/docs/extensions/attr_list.txt
+++ b/docs/extensions/attr_list.txt
@@ -78,3 +78,11 @@ immediately after the inline element with no whitespace.
 The above results in the following output:
 
     <p><a href="http://example.com" class="foo bar" title="Some title!">link</a></p>
+
+Usage
+-----
+
+See [Extensions](./index.html) for general extension usage, specify `attr_list`
+as the name of the extension.
+
+This extension does not accept any special configuration options.
diff --git a/docs/extensions/definition_lists.txt b/docs/extensions/definition_lists.txt
index a5ba393..3a62f6a 100644
--- a/docs/extensions/definition_lists.txt
+++ b/docs/extensions/definition_lists.txt
@@ -32,7 +32,7 @@ Thus, the following text (taken from the above referenced PHP documentation):
     Orange
     :   The fruit of an evergreen tree of the genus Citrus.
 
-will be rendered like so:
+will be rendered as:
 
     <dl>
     <dt>Apple</dt>
@@ -47,15 +47,7 @@ will be rendered like so:
 Usage
 -----
 
-From the Python interpreter:
+See [Extensions](./index.html) for general extension usage, specify `def_list`
+as the name of the extension.
 
-    >>> html = markdown.markdown(text, ['def_list'])
-
-To use with other extensions, just add them to the list, like this:
-
-    >>> html = markdown.markdown(text, ['def_list', 'footnotes'])
-
-The extension can also be called from the command line using Markdown's `-x` 
-parameter:
-
-    python -m markdown -x def_list source.txt > output.html
+This extension does not accept any special configuration options.
diff --git a/docs/extensions/fenced_code_blocks.txt b/docs/extensions/fenced_code_blocks.txt
index 0148c80..b03c886 100644
--- a/docs/extensions/fenced_code_blocks.txt
+++ b/docs/extensions/fenced_code_blocks.txt
@@ -35,7 +35,7 @@ Fenced code blocks can have a blank line as the first  and/or last line of a
 code block and they can also come immediately after a list item without becoming
 part of the list.
 
-### Language
+### Language ###
 
 In addition to PHP Extra's syntax, you can define the language of the code 
 block for use by syntax highlighters etc. The language will be assigned as a 
@@ -60,7 +60,7 @@ The above will output:
     <pre><code class="html">&lt;p&gt;HTML Document&lt;/p&gt;
     </code></pre>
 
-[Github][]'s tilde (`\``) syntax is also supported:
+[Github][]'s backtick (`\``) syntax is also supported:
 
     ```python
     # more python code
@@ -68,17 +68,23 @@ The above will output:
 
 [Github]: http://github.github.com/github-flavored-markdown/
 
-### Emphasized Lines
+### Emphasized Lines ###
 
-If [Pygments][] is installed, this extension can emphasize certain lines of
-code. By default, emphasized lines have a yellow background. This is useful to
-direct the reader's attention. The lines can be specified with PHP Extra's
-syntax:
+If you would like to have your fenced code blocks highlighted with the 
+[CodeHilite][] extension, simply enable that extension (remember that
+[Pygments][] is its dependency) and the language of your fenced code blocks
+will be passed in and highlighted appropriately.
+
+Similar to the [colon][] syntax of the CodeHilite extension, fenced code blocks
+can also have emphasized certain lines of code.
+
+The lines can be specified with PHP Extra's syntax:
 
     ~~~~{.python hl_lines="1 3"}
     # This line is emphasized
     # This line isn't
     # This line is emphasized
+    ~~~~
 
 ... or with GitHub's:
 
@@ -86,22 +92,16 @@ syntax:
     # This line is emphasized
     # This line isn't
     # This line is emphasized
+    ```
 
-(`hl_lines` is named for Pygments' "highlighted lines" option.)
-
+[CodeHilite]: code_hilite.html
 [Pygments]: http://pygments.org/
+[colon]: ./code_hilite.html#colons
 
 Usage
 -----
 
-From the Python interpreter:
-
-    >>> html = markdown.markdown(text, ['fenced_code'])
-
-If you would like to have your fenced code blocks highlighted with the 
-[CodeHilite][] extension, simply include that extension and the language 
-of your fenced code blocks will be passed in and highlighted appropriately.
-
-    >>> html = markdown.markdown(text, ['fenced_code', 'codehilite'])
+See [Extensions](./index.html) for general extension usage, specify `fenced_code`
+as the name of the extension.
 
-[CodeHilite]: code_hilite.html
+This extension does not accept any special configuration options.
diff --git a/docs/extensions/footnotes.txt b/docs/extensions/footnotes.txt
index e06344b..e3207a1 100644
--- a/docs/extensions/footnotes.txt
+++ b/docs/extensions/footnotes.txt
@@ -10,9 +10,9 @@ Footnotes
 Summary
 -------
 
-An extension to Python-Markdown that adds footnote syntax. This extension has 
-been included with Python-Markdown since 1.7 and should be available to anyone 
-who has a typical install of Python-Markdown.
+An extension to Python-Markdown that adds footnote syntax.
+
+This extension is included in the standard Markdown library.
 
 Syntax
 ------
@@ -28,14 +28,14 @@ Example:
 
     Footnotes[^1] have a label[^@#$%] and the footnote's content.
 
-    [^1]: This is a footnote's content.
+    [^1]: This is a footnote content.
     [^@#$%]: A footnote on the label: "@#$%".
 
 A footnote label must start with a caret `^` and may contain any inline text 
 (including spaces) between a set of square brackets `[]`. Only the first
 caret has any special meaning.
 
-A footnote's content must start with the label followed by a colon and at least 
+A footnote content must start with the label followed by a colon and at least 
 one space. The label used to define the content must exactly match the label used
 in the body (including capitalization and whitespace). The content would then 
 follow the label either on the same line or on the next line. The content may 
@@ -47,7 +47,6 @@ When working with multiple blocks, it may be helpful to start the content on a
 separate line from the label which defines the content. This way the entire block 
 is indented consistently and any errors are more easily discernible by the author.
 
-
     [^1]: 
         The first paragraph of the definition.
 
@@ -60,22 +59,29 @@ is indented consistently and any errors are more easily discernible by the autho
 
         A final paragraph.
 
-By default, the footnote definitions are placed at the end of the resulting 
-HTML document. However, you may want the footnotes in another location within 
-the document. Simply place the following text at that location within your 
-markdown document (See how to configure this text below):
-
-    ///Footnotes Go Here///
 
 Usage
 -----
 
-From the Python interpreter:
+See [Extensions](./index.html) for general extension usage, specify `footnotes`
+as the name of the extension.
+
+See the [Library Reference](../reference.html#extensions) for information about
+configuring extensions.
 
-    >>> html = markdown.markdown(text, ['footnotes'])
+The following options are provided to configure the output:
 
-To configure the place marker for footnote definitions (just be sure not to 
-use any existing markdown syntax):
+* **PLACE_MARKER**:
+    A text string used to mark the position where the footnotes are rendered.
+    Defaults to `///Footnotes Go Here///`.
 
-    >>> html = markdown.markdown(text, ['footnotes(PLACE_MARKER=+++my marker+++)'])
+    If the place marker text is not found in the document, the footnote
+    definitions are placed at the end of the resulting HTML document.
 
+* **UNIQUE_IDS**:
+    Whether to avoid collisions across multiple calls to `reset()`. Defaults to
+    `False`.
+    
+* **BACKLINK_TEXT**:
+    The text string that links from the footnote definition back to the position
+    in the document. Defaults to `&#8617;`.
diff --git a/docs/extensions/smart_strong.txt b/docs/extensions/smart_strong.txt
index fd3bae6..aa34ed7 100644
--- a/docs/extensions/smart_strong.txt
+++ b/docs/extensions/smart_strong.txt
@@ -10,14 +10,16 @@ Smart_Strong
 Summary
 -------
 
-The Markdown Smart_Strong Extension adds smarter handling of double underscores
-within words. This does for double underscores what
-[smart_emphasis](../reference.html#smart_emphasis) does for single underscores.
+The Smart_Strong Extension adds smarter handling of double underscores within
+words. This does for double underscores what [smart_emphasis][] does for single
+underscores.
 
 The Smart_Strong Extension is included in the standard Markdown library.
 
-Usage
------
+[smart_emphasis]: ../reference.html#smart_emphasis
+
+Example
+-------
 
     >>> import markdown
     >>> markdown.markdown('Text with double__underscore__words.', \
@@ -30,8 +32,10 @@ Usage
                           extensions=['smart_strong'])
     u'<p><strong>this__works__too</strong>.</p>'
 
-This extension is also included with the [Extra](extra.html) Extension. You may
-call that extension to get this behavior with all the other features of 'Extra'.
+Usage
+-----
 
-    >>> markdown.markdown(text, extensions=['extra'])
+See [Extensions](./index.html) for general extension usage, specify `smart_strong`
+as the name of the extension.
 
+This extension does not accept any special configuration options.
diff --git a/docs/extensions/tables.txt b/docs/extensions/tables.txt
index bb0872a..820d5a5 100644
--- a/docs/extensions/tables.txt
+++ b/docs/extensions/tables.txt
@@ -52,7 +52,7 @@ will be rendered as:
 Usage
 -----
 
-From the Python interpreter:
-
-    >>> html = markdown.markdown(text, ['tables'])
+See [Extensions](./index.html) for general extension usage, specify `tables`
+as the name of the extension.
 
+This extension does not accept any special configuration options.