From 70c81659eca814bb037b93c95996210d192e5ca5 Mon Sep 17 00:00:00 2001
From: Waylan Limberg <waylan@gmail.com>
Date: Wed, 18 Mar 2009 23:29:40 -0400
Subject: Added documentation for Extra Extension and all the extentions it
 supports. Still need to do non-extra extensions.

---
 docs/extensions/Abbreviations.txt      |  53 +++++++++++++++++
 docs/extensions/Definition_Lists.txt   |  55 +++++++++++++++++
 docs/extensions/Fenced_Code_Blocks.txt |  63 ++++++++++++++++++++
 docs/extensions/HeaderId.txt           | 104 +++++++++++++++++++++++++++++++++
 docs/extensions/Tables.txt             |  53 +++++++++++++++++
 docs/extensions/extra.txt              |  43 ++++++++++++++
 docs/extensions/footnotes.txt          |  62 ++++++++++++++++++++
 7 files changed, 433 insertions(+)
 create mode 100644 docs/extensions/Abbreviations.txt
 create mode 100644 docs/extensions/Definition_Lists.txt
 create mode 100644 docs/extensions/Fenced_Code_Blocks.txt
 create mode 100644 docs/extensions/HeaderId.txt
 create mode 100644 docs/extensions/Tables.txt
 create mode 100644 docs/extensions/extra.txt
 create mode 100644 docs/extensions/footnotes.txt

(limited to 'docs')

diff --git a/docs/extensions/Abbreviations.txt b/docs/extensions/Abbreviations.txt
new file mode 100644
index 0000000..fa54d3c
--- /dev/null
+++ b/docs/extensions/Abbreviations.txt
@@ -0,0 +1,53 @@
+Abbreviations
+-------------
+
+Summary
+-------
+
+The Markdown 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.
+
+Syntax
+------
+
+Abbreviations are defined using the syntax established in 
+[PHP Markdown Extra][php].
+
+[php]: http://www.michelf.com/projects/php-markdown/extra/#abbr
+
+Thus, the following text (taken from the above referenced PHP documentation):
+
+    The HTML specification 
+    is maintained by the W3C.
+        
+    *[HTML]: Hyper Text Markup Language
+    *[W3C]:  World Wide Web Consortium
+
+will be rendered like so:
+
+    <p>The <abbr title="Hyper Text Markup Language">HTML</abbr> specification 
+    is maintained by the <abbr title="World Wide Web Consortium">W3C</abbr>.</p>
+
+Usage
+-----
+
+From the Python interpreter:
+
+    >>> 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:
+
+    markdown.py -x abbr source.txt > output.html
diff --git a/docs/extensions/Definition_Lists.txt b/docs/extensions/Definition_Lists.txt
new file mode 100644
index 0000000..983070d
--- /dev/null
+++ b/docs/extensions/Definition_Lists.txt
@@ -0,0 +1,55 @@
+Definition Lists
+----------------
+
+Summary
+-------
+
+The Definition List Extension adds the ability to create definition list in
+Markdown documents.
+
+This extension is included in the standard Markdown library.
+
+Syntax
+------
+
+Definition lists are defined using the syntax established in 
+[PHP Markdown Extra][php].
+
+[php]: http://www.michelf.com/projects/php-markdown/extra/#def-list
+
+Thus, the following text (taken from the above referenced PHP documentation):
+
+    Apple
+    :   Pomaceous fruit of plants of the genus Malus in 
+        the family Rosaceae.
+
+    Orange
+    :   The fruit of an evergreen tree of the genus Citrus.
+
+will be rendered like so:
+
+    <dl>
+    <dt>Apple</dt>
+    <dd>Pomaceous fruit of plants of the genus Malus in 
+    the family Rosaceae.</dd>
+
+    <dt>Orange</dt>
+    <dd>The fruit of an evergreen tree of the genus Citrus.</dd>
+    </dl>
+
+
+Usage
+-----
+
+From the Python interpreter:
+
+    >>> 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:
+
+    markdown.py -x def_list source.txt > output.html
diff --git a/docs/extensions/Fenced_Code_Blocks.txt b/docs/extensions/Fenced_Code_Blocks.txt
new file mode 100644
index 0000000..6b1ba76
--- /dev/null
+++ b/docs/extensions/Fenced_Code_Blocks.txt
@@ -0,0 +1,63 @@
+Fenced Code Blocks
+==================
+
+Summary
+-------
+
+This extension adds a secondary way to define code blocks which overcomes a few
+limitations of the indented code blocks.
+
+This extension is included in the standard Markdown library.
+
+Syntax
+------
+
+Fenced Code Blocks are defined using the syntax established in 
+[PHP Markdown Extra][php].
+
+[php]: http://www.michelf.com/projects/php-markdown/extra/#fenced-code-blocks
+
+Thus, the following text (taken from the above referenced PHP documentation):
+
+    This is a paragraph introducing:
+
+    ~~~~~~~~~~~~~~~~~~~~
+    a one-line code block
+    ~~~~~~~~~~~~~~~~~~~~
+
+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.
+
+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 
+class attribute of the ``<code>`` element in the output. Therefore, you should 
+define the language as you would a css class - ``.language``. For consistency 
+with other markdown syntax, the language can *optionally* be wrapped in curly 
+brackets:
+
+    ~~~~{.python}
+    # python code
+    ~~~~
+
+    ~~~~.html
+    <p>HTML Document</p>
+    ~~~~
+
+The above will output:
+
+    <pre><code class="python"># python code
+    </code></pre>
+    
+    <pre><code class="html">&lt;p&gt;HTML Document&lt;/p&gt;
+    </code></pre>
+
+Usage
+-----
+
+From the Python interpreter:
+
+    >>> html = markdown.markdown(text, ['fenced_code'])
+
+
+
diff --git a/docs/extensions/HeaderId.txt b/docs/extensions/HeaderId.txt
new file mode 100644
index 0000000..efd1eb8
--- /dev/null
+++ b/docs/extensions/HeaderId.txt
@@ -0,0 +1,104 @@
+HeaderId
+========
+
+Summary
+-------
+
+An extension to Python-Markdown that adds an 'id' attribute to HTML header 
+elements (h1-h6) in markdown's output.
+
+This extension is included in the standard Markdown library.
+
+Syntax
+------
+
+The basic syntax follows [PHP Markdown Extra][]'s implementation:
+
+[PHP Markdown Extra]: http://michelf.com/projects/php-markdown/extra/#header-id
+
+    Header 1            {#header1}
+    ========
+
+    ## Header 2 ##      {#header2}
+
+will result in the following HTML:
+
+    <h1 id="header1">Header 1</h1>
+
+    <h2 id="header2">Header 2</h2>
+
+However, there is much more that this extension does.
+
+By default, all headers will automatically have unique "id" attributes 
+generated based upon the text of the header (See below to turn this off). 
+Note this example in which all three headers would have the same "id":
+
+    #Header
+    #Another Header {#header}
+    #Header
+
+Results in:
+
+    <h1 id="header">Header</h1>
+    <h1 id="header_1">Another Header</h1>
+    <h1 id="header_2">Third Header</h1>
+
+Configuring the Output
+----------------------
+
+The HeaderId extension has two configuration settings:
+
+* **level**: Base level for headers.
+
+    Default: `1`
+
+* **forceid**: Force all headers to have an id.
+
+    Default: `True`
+
+The `level` setting allows you to automatically adjust the header levels to fit
+within the hierarchy of your html templates. For example, the markdown text for
+this page should not contain any headers higher than level 3 (`<h3>`). 
+Therefore, do the following:
+
+    >>>  text = '''
+    ... #Some Header
+    ... ## Next Level'''
+    >>> html = markdown.markdown(text, ['headerid(level=3)'])
+    >>> print html
+    <h3 id="some_header">Some Header</h3>
+    <h4 id="next_level">Next Level</h4>'
+
+The `forceid` setting turns on or off the automatically generated ids for 
+headers that do not have one explicitly defined.
+
+    >>> text = '''
+    ... # Some Header
+    ... # Header with ID # { #foo }'''
+    >>> html = markdown.markdown(text, ['headerid(forceid=False)'])
+    >>> print html
+    <h1>Some Header</h1>
+    <h1 id="foo">Header with ID</h1>
+
+Using with Meta-Data
+--------------------
+
+The HeaderId Extension also supports the [[Meta-Data]] Extension. Please see the documentation for that extension for specifics. The supported meta-data keywords are:
+
+* `header_level`
+* `header_forceid`
+
+When used, the meta-data will override the settings provided through the  
+`extension_configs` interface. 
+
+This document:
+
+    header_level: 2
+    header_forceid: Off
+
+    # A Header
+
+
+Will result in the following output:
+
+    <h2>A Header</h2>
diff --git a/docs/extensions/Tables.txt b/docs/extensions/Tables.txt
new file mode 100644
index 0000000..63d6849
--- /dev/null
+++ b/docs/extensions/Tables.txt
@@ -0,0 +1,53 @@
+Tables
+----------------
+
+Summary
+-------
+
+The Table Extension adds the ability to create tables in Markdown documents.
+
+This extension is included in the standard Markdown library.
+
+Syntax
+------
+
+Tables are defined using the syntax established in [PHP Markdown Extra][php].
+
+[php]: http://www.michelf.com/projects/php-markdown/extra/#table
+
+Thus, the following text (taken from the above referenced PHP documentation):
+
+First Header  | Second Header
+------------- | -------------
+Content Cell  | Content Cell
+Content Cell  | Content Cell
+
+will be rendered as:
+
+<table>
+<thead>
+<tr>
+<th>First Header</th>
+<th>Second Header</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Content Cell</td>
+<td>Content Cell</td>
+
+</tr>
+<tr>
+<td>Content Cell</td>
+<td>Content Cell</td>
+</tr>
+</tbody>
+</table>
+
+Usage
+-----
+
+From the Python interpreter:
+
+    >>> html = markdown.markdown(text, ['tables'])
+
diff --git a/docs/extensions/extra.txt b/docs/extensions/extra.txt
new file mode 100644
index 0000000..817d58f
--- /dev/null
+++ b/docs/extensions/extra.txt
@@ -0,0 +1,43 @@
+Python-Markdown Extra
+=====================
+
+Summary
+-------
+
+A compilation of various Python-Markdown extensions that (mostly) imitates
+[PHP Markdown Extra](http://michelf.com/projects/php-markdown/extra/).
+
+The supported extensions include:
+
+* [[Abbreviations]]
+* [[Definition_Lists]]
+* [[Fenced_Code_Blocks]]
+* [[Footnotes]]
+* [[HeaderId]]
+* [[Tables]]
+
+See each individual extension for syntax documentation. Extra and all it's 
+supported extensions are included in the standard Markdown library.
+
+Usage
+-----
+
+From the Python interpreter:
+
+    >>> import markdown
+    >>> html = markdown.markdown(text, ['extra'])
+
+In the unlikely event that one or more of the supported extensions are not
+available for import, Markdown will simply continue without that
+extension. If you would like to be notified of such failures,
+you may set Python-Markdown's logger level to "WARN".
+
+There may be additional extensions that are distributed with
+Python-Markdown that are not included here in Extra. Those extensions
+are not part of PHP Markdown Extra, and therefore, not part of
+Python-Markdown Extra. If you really would like Extra to include
+additional extensions, we suggest creating your own clone of Extra
+under a different name (see [[Writing Extensions]]). You could also 
+edit the `extensions` global variable defined in the source, but be 
+aware that such changes may be lost when you upgrade to any future 
+version of Python-Markdown.
diff --git a/docs/extensions/footnotes.txt b/docs/extensions/footnotes.txt
new file mode 100644
index 0000000..7188f44
--- /dev/null
+++ b/docs/extensions/footnotes.txt
@@ -0,0 +1,62 @@
+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.
+
+Syntax
+------
+
+Python-Markdown's Footnote syntax follows the generally accepted syntax of the 
+Markdown community at large and almost exactly matches [PHP Markdown Extra][]'s
+implementation of footnotes. The only differences involve a few subtleties in 
+the output.
+
+[PHP Markdown Extra]: http://michelf.com/projects/php-markdown/extra/#footnotes
+
+Example:
+
+    Footnotes[^1] have a label[^label] and a definition[^!DEF].
+
+    [^1]: This is a footnote
+    [^label]: A footnote on "label"
+    [^!DEF]: The definition of a footnote.
+
+A footnote definition may contain multiple lines, paragraphs, code blocks, 
+blockquotes and most any other markdown syntax. The additional line simply 
+must be indented at least an additional four spaces.
+
+    [^1]: The first paragraph of the definition.
+
+        Paragraph two of the definition.
+
+        > A blockquote with
+        > multiple lines.
+
+            a code block
+
+        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:
+
+    >>> html = markdown.markdown(text, ['footnotes'])
+
+To configure the place marker for footnote definitions (just be sure not to 
+use any existing markdown syntax):
+
+    >>> html = markdown.markdown(text, ['footnotes(PLACE_MARKER=+++my marker+++)'])
+
-- 
cgit v1.2.3