docs: improved documentation of the extra/ extensions

Simplified, unified style, added some undocumented options.

NOTE: Footnotes/UNIQUE_IDS stays mostly undocumented

1 files changed, 23 insertions, 17 deletions

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 `↩`.