aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorWaylan Limberg <waylan@gmail.com>2007-12-13 03:47:22 +0000
committerWaylan Limberg <waylan@gmail.com>2007-12-13 03:47:22 +0000
commit158b8ee673be7aea09e15c3830092bcab62dbfbe (patch)
tree5ac33672b0f2ee68423b9c52e3ee2d365a7c7326
parentf0a39551f6e63313630613a76b2f645e6f5094fe (diff)
downloadmarkdown-158b8ee673be7aea09e15c3830092bcab62dbfbe.tar.gz
markdown-158b8ee673be7aea09e15c3830092bcab62dbfbe.tar.bz2
markdown-158b8ee673be7aea09e15c3830092bcab62dbfbe.zip
Updated docs.
-rw-r--r--CHANGE_LOG.txt2
-rw-r--r--README.html91
-rw-r--r--README.txt98
-rw-r--r--home_page.txt338
-rw-r--r--sidebar.txt37
5 files changed, 191 insertions, 375 deletions
diff --git a/CHANGE_LOG.txt b/CHANGE_LOG.txt
index 405a025..0d8b2d2 100644
--- a/CHANGE_LOG.txt
+++ b/CHANGE_LOG.txt
@@ -1,6 +1,8 @@
PYTHON MARKDOWN CHANGELOG
=========================
+Dec 12, 2007: Updated docs.
+
Nov 29, 2007: Added support for images inside links. Also fixed
a few bugs in the footnote extension.
diff --git a/README.html b/README.html
new file mode 100644
index 0000000..6d94e8e
--- /dev/null
+++ b/README.html
@@ -0,0 +1,91 @@
+<h1><a href="http://freewisdom.org/projects/python-markdown">Python-Markdown</a></h1>
+<p>This is a Python implementation of John Gruber's <a href="http://daringfireball.net/projects/markdown/">Markdown</a>.
+ It is almost completely compliant with the reference implementation,
+ though there are a few known issues. See <a href="http://www.freewisdom.org/projects/python-markdown/Features">Features</a> for information
+ on what exactly is supported and what is not. Additional features are
+ supported by the <a href="http://www.freewisdom.org/projects/python-markdown/Available_Extensions">Available Extensions</a>.
+</p>
+
+<h2>Installation</h2>
+<p>To install Python Markdown <a href="http://sourceforge.net/project/showfiles.php?group_id=153041">download</a> the zip file and extract the
+ files. If you want to install markdown as a module into your python
+ tree, run <code>sudo python setup.py install</code> from a directory where you
+ unzip the files.
+</p>
+
+<h2>Command Line Usage</h2>
+<p>To use markdown.py from the command line, run it as
+</p>
+<pre><code>python markdown.py &lt;input_file&gt;
+</code></pre><p>or
+</p>
+<pre><code>python markdown.py &lt;input_file&gt; &gt; &lt;output_file&gt;
+</code></pre><p>For more details, use the <code>-h</code> or <code>--help</code> options from the command line
+ or read the <a href="http://www.freewisdom.org/projects/python-markdown/Command_Line">Command Line Docs</a> available online.
+</p>
+
+<h2>Using as a Python Module</h2>
+<p>To use markdown as a module:
+</p>
+<pre><code>import markdown
+html = markdown.markdown(your_text_string)
+</code></pre><p>For more details see the <a href="http://www.freewisdom.org/projects/python-markdown/Using_as_a_Module">Module Docs</a>.
+</p>
+
+<h2>Support</h2>
+<p>You may ask for help and discuss various other issues on the <a href="http://lists.sourceforge.net/lists/listinfo/python-markdown-discuss">mailing list</a> and report bugs on the <a href="http://sourceforge.net/tracker/?func=add&amp;group_id=153041&amp;atid=790198">bug tracker</a>.
+</p>
+
+<h2>Credits</h2>
+<ul>
+ <li>
+ Most of the code currently in the module was written by <a href="http://www.freewisdom.org">Yuri Takhteyev</a>
+ while procrastinating from his Ph.D.
+ </li>
+
+ <li>
+ The original version of this script was written by <a href="http://www.dwerg.net/">Manfred Stienstra</a>,
+ who is responsible for about a quarter of the code.
+ </li>
+
+ <li>
+ Many recent bugs are being fixed by <a href="http://achinghead.com/">Waylan Limberg</a>.
+ </li>
+</ul>
+<p>Other contributions:
+</p>
+<ul>
+ <li>
+ Daniel Krech provided the setup.py script.
+ </li>
+
+ <li>
+ G. Clark Haynes submitted a patch for indented lists.
+ </li>
+
+ <li>
+ Tiago Cogumbreiro submitted an email autolink fix.
+ </li>
+
+ <li>
+ Sergej Chodarev submitted a patch for treatment of <code>&lt;hr/&gt;</code> tags.
+ </li>
+
+ <li>
+ Chris Clark submitted a patch to handle <code>&lt;mailto:...&gt;</code> syntax and a reg ex
+ for &quot;smart&quot; emphasis (ignoring underscores within a word).
+ </li>
+
+ <li>
+ Steward Midwinter wrote command-line parser and cleaned up comments.
+ </li>
+
+ <li>
+ Many other people helped by reporting bugs.
+ </li>
+</ul>
+
+<h2>License</h2>
+<p>The code is dual-licensed under <a href="http://www.gnu.org/copyleft/gpl.html)">GPL</a> and <a href="http://www.opensource.org/licenses/bsd-license.php">BSD License</a>. Other
+ licensing arrangements can be discussed.
+</p> \ No newline at end of file
diff --git a/README.txt b/README.txt
new file mode 100644
index 0000000..b859924
--- /dev/null
+++ b/README.txt
@@ -0,0 +1,98 @@
+[Python-Markdown][]
+===================
+
+This is a Python implementation of John Gruber's [Markdown][].
+It is almost completely compliant with the reference implementation,
+though there are a few known issues. See [Features][] for information
+on what exactly is supported and what is not. Additional features are
+supported by the [Available Extensions][].
+
+[Python-Markdown]: http://freewisdom.org/projects/python-markdown
+[Markdown]: http://daringfireball.net/projects/markdown/
+[Features]: http://www.freewisdom.org/projects/python-markdown/Features
+[Available Extensions]: http://www.freewisdom.org/projects/python-markdown/Available_Extensions
+
+
+Installation
+------------
+
+To install Python Markdown [download][] the zip file and extract the
+files. If you want to install markdown as a module into your python
+tree, run `sudo python setup.py install` from a directory where you
+unzip the files.
+
+[download]: http://sourceforge.net/project/showfiles.php?group_id=153041
+
+
+Command Line Usage
+------------------
+
+To use markdown.py from the command line, run it as
+
+ python markdown.py <input_file>
+
+or
+
+ python markdown.py <input_file> > <output_file>
+
+For more details, use the `-h` or `--help` options from the command line
+or read the [Command Line Docs][] available online.
+
+[Command Line Docs]: http://www.freewisdom.org/projects/python-markdown/Command_Line
+
+
+
+Using as a Python Module
+------------------------
+
+To use markdown as a module:
+
+ import markdown
+ html = markdown.markdown(your_text_string)
+
+For more details see the [Module Docs][].
+
+[Module Docs]: http://www.freewisdom.org/projects/python-markdown/Using_as_a_Module
+
+Support
+-------
+
+You may ask for help and discuss various other issues on the [mailing list][] and report bugs on the [bug tracker][].
+
+[mailing list]: http://lists.sourceforge.net/lists/listinfo/python-markdown-discuss
+[bug tracker]: http://sourceforge.net/tracker/?func=add&group_id=153041&atid=790198
+
+
+Credits
+-------
+
+* Most of the code currently in the module was written by [Yuri Takhteyev][]
+ while procrastinating from his Ph.D.
+* The original version of this script was written by [Manfred Stienstra][],
+ who is responsible for about a quarter of the code.
+* Many recent bugs are being fixed by [Waylan Limberg][].
+
+Other contributions:
+
+* Daniel Krech provided the setup.py script.
+* G. Clark Haynes submitted a patch for indented lists.
+* Tiago Cogumbreiro submitted an email autolink fix.
+* Sergej Chodarev submitted a patch for treatment of `<hr/>` tags.
+* Chris Clark submitted a patch to handle `<mailto:...>` syntax and a reg ex
+ for "smart" emphasis (ignoring underscores within a word).
+* Steward Midwinter wrote command-line parser and cleaned up comments.
+* Many other people helped by reporting bugs.
+
+[Yuri Takhteyev]: http://www.freewisdom.org
+[Manfred Stienstra]: http://www.dwerg.net/
+[Waylan Limberg]: http://achinghead.com/
+
+
+License
+-------
+
+The code is dual-licensed under [GPL][] and [BSD License][]. Other
+licensing arrangements can be discussed.
+
+[GPL]: http://www.gnu.org/copyleft/gpl.html)
+[BSD License]: http://www.opensource.org/licenses/bsd-license.php
diff --git a/home_page.txt b/home_page.txt
deleted file mode 100644
index 89a9cc4..0000000
--- a/home_page.txt
+++ /dev/null
@@ -1,338 +0,0 @@
-<?php include("markdown-header.php");?>
- <div id="blog_entry">
- <div class="blogbody">
-
-<a name="Summary"></a>
-<h3 class="title">Summary</h3>
-
-This is a Python implementation of John Gruber's
-[Markdown](http://daringfireball.net/projects/markdown/).
-The current version of python-markdown implements all Markdown syntax
-features and fully passes [Markdown Test Suite
-1.0](http://six.pairlist.net/pipermail/markdown-discuss/2004-December/000909.html). It also supports footnotes (see [this
-thread](http://six.pairlist.net/pipermail/markdown-discuss/2005-August/001480.html))
-and attributes (see [this
-thread](http://six.pairlist.net/pipermail/markdown-discuss/2005-August/001486.html)). Python-Markdown defaults to ignoring middle-word emphasis through
-underscore, but this it can be switched off. (See [this
-thread](http://six.pairlist.net/pipermail/markdown-discuss/2005-October/001610.html)
-for discussion.)
-
-If you find something missing, [submit a bug report](http://sourceforge.net/tracker/?func=add&group_id=153041&atid=790198) or send me an email (qaramazov-at-gmail.com). Better yet, send me a patch.
-
-<a name="Installation"></a>
-<h3 class="title">Installation</h3>
-
-[Download](http://sourceforge.net/project/showfiles.php?group_id=153041)
-the zip file and extract the files. If you want to install markdown
-as as a module into your python tree, run "sudo python setup.py
-install" from a directory where you unzip the files. (You typically
-need to be root to install modules this way - hence use of "sudo". If
-you don't have root access, it probably doesn't make sense for you to
-"install" markdown this way - just put the markdown.py file somewhere
-and make sure that directory is in your path later.)
-
-<a name="Commandline"></a>
-<h3 class="title">Command Line Usage</h3>
-
-To use markdown.py by itself, run it as
-
- python markdown.py <input_file>
-
-or
-
- python markdown.py <input_file> > <output_file>
-
-If you are using Python 2.3 or higher, you can also use advanced
-command line options to specify encoding or to run extensions.
-
-
- $ python markdown.py
- usage: markdown.py INPUTFILE [options]
-
- options:
- -h, --help show this help message and exit
- -f OUTPUT_FILE, --file=OUTPUT_FILE
- write output to OUTPUT_FILE
- -e ENCODING, --encoding=ENCODING
- encoding for input and output files
- -q, --quiet suppress all messages
- -v, --verbose print info messages
- -s, --safe same mode (strip user's HTML tag)
- --noisy print debug messages
- -x EXTENSION, --extension=EXTENSION
- load extension EXTENSION
-
-For an extension to be ran this way it must be provided in a module
-named ``mdx_{extensionname}.py`` which should be in your python path,
-e.g. ``mdx_footnotes.py``. It can then be invoked as by name (the
-part after "mdx_"):
-
- python markdown.py -x footnotes text_with_footnotes.txt output.html
-
-If the extension supports config options (see below), you can also
-pass them in as well:
-
- python markdown.py -x "footnotes(PLACE_MARKER=~~~~~~~~)"
-
-<a name="Module"></a>
-<h3 class="title">Using the Module</h3>
-
-To use markdown as a module:
-
- import markdown
- html = markdown.markdown(your_text_string)
-
-Alternatively, if you want to pass more options:
-
- import markdown
- md = Markdown(text,
- extensions=['footnotes'],
- extension_configs= {'footnotes' :
- ('PLACE_MARKER','~~~~~~~~')}
- encoding='utf8',
- safe_mode = True)
-
- return md.toString()
-
-or, if you want to process multiple strings:
-
- md = Markdown(text=None)
- md.toString(text)
-
-Note that if you are using Markdown on a web system which will
-transform text provided by untrusted users, you may want to use
-"safe_mode=True" option (see above) which ensures that user's HTML tags are
-removed. (They can still create links using Markdown syntax.)
-
-<a name="Extending"></a>
-<h3 class="title">Writing Extensions</h3>
-
-The functionality of the script can be extended without changing the
-code, by inserting additional pre-processors, post-processors or
-inline patterns into Markdown's pipeline.
-
-**Pre-processors** operate on lines of source text and are run in the
-beginning. It is sufficient to write a class with a run() method that
-takes a list of text lines as a parameter and returns the same or a
-new list. An instance of the preprocessor can then be inserted into
-the markdown pipeline. Preprocessor classes must extend
-``markdown.Preprocessor``.
-
- class SamplePreprocessor (markdown.Preprocessor) :
- def run(self, lines) :
- for i in range(len(lines)) :
- if lines[i].startswith(SOMETHING) :
- lines[i] = do_something(lines[i])
-
- return lines
-
- md_instance.preprocessors.insert(SOME_INDEX, SamplePreprocessor())
-
-**Post-processors** operate on a NanoDom tree and run at the very end.
-They need to implement a "run" method that takes a pointer to a NanoDom
-document. Postprocessor classes must extend ``markdown.Postprocessor``.
-
- class SamplePostprocessor (markdown.Postprocessor):
- def run(self, doc) :
- doc.documentElement.appendChild(doc.createElement("new"))
-
-
- md_instance.postprocessors.insert(SOME_INDEX, SamplePostprocessor())
-
-Finally, **inline patterns** can be added. Each inline pattern
-includes a regular expression pattern and a method for turning a match
-object into a DOM fragment
-
- class MyCustomPattern (markdown.Pattern) :
- def handleMatch(self, m, doc) :
- el = doc.createElement('custom')
- el.setAttribute('stuff', m.group(3))
- return el
-
- new_pattern = MyCustomPattern(r'your regular expression here')
- md_instance.inlinePatterns.insert(SOME_INDEX, new_pattern)
-
-Preprocessors, patterns and postprocessors need to then be wrapped
-together into an extension, which should be implemented as a class
-that extends markdown.Extension and should over-ride the
-``extendMarkdown()`` method. ``extendMarkdown()`` is called during
-markdown construction, giving the extension a pointer to the markdown
-object (the ``md`` parameters) and markdown's global variables
-(``md_globals``), which in theory gives the extension an option of
-changing anything it cares to change. However, what it really should
-be doing is inserting preprocessors, postprocessors and patterns into
-the markdown pipeline:
-
-
- def extendMarkdown(self, md, md_globals) :
-
- self.md = md
-
- # Insert a preprocessor before ReferencePreprocessor
- index = md.preprocessors.index(md_globals['REFERENCE_PREPROCESSOR'])
- preprocessor = FootnotePreprocessor(self)
- preprocessor.md = md
- md.preprocessors.insert(index, preprocessor)
-
-
-If the extension uses any parameters that the use may want to change,
-they should be stored in self.config in the following format:
-
- self.config = {parameter_1_name : [value1, description1],
- parameter_2_name : [value2, description2] }
-
-When stored this way the config parameters can be over-riden from the
-command line or at the time Markdown is instantiated:
-
- markdown.py -x myextension(SOME_PARAM=2) inputfile.txt > output.txt
-
-Note that parameters should always be assumed to be set to string
-values, and should be converted at the run time, e.g.
-
- i += int(self.getConfig("SOME_PARAM"))
-
-Each extension should ideally be placed in its own module starting
-with ``mdx_`` prefix (e.g. ``mdx_footnotes.py``). The module must
-provide a module-level function called ``makeExtensions`` that takes
-as an optional parameter a list of configuration over-rides and
-returns an instance of the extension. E.g.:
-
- def makeExtension(configs=None) :
- return FootnoteExtension(configs=configs)
-
-See the implementation of footnote support distributed with the
-markdown script (mdx_footnotes.py) for an example of using all three
-in combination to provide reasonably complex additional functionality.
-(I use a pre-processor to collect footnote definitions, an inline
-pattern to handle uses of footnotes inside the text and a
-post-processor to attach the HTML of the actual footnotes at the end
-of the document) The RSS extension (mdx_rss.py, also included), which
-generates an RSS file from markdown source is a simpler extension but
-provides an example of extending markdown to generate arbitrary XML
-rather than HTML.
-
-
-Other extensions:
-
-* [Table-of-contents extension](extensions/mdx_toc.py) by Chris Clark
- (inserts a table of contents), upgraded by
- Yuri.
-
-* [Title extension](extensions/mdx_title.py) by Chris Clark (inserts a
- title element)
-
-* [WikiLinks](http://achinghead.com/archives/67/adding-wikilinks-to-markdown-in-python/)
- by Waylan Limberg (not yet upgraded)
-
-
-<a name="Django"></a>
-<h3 class="title">Using Markdown with Django</h3>
-
-Install markdown and make sure it is in your path.
-Include 'django.contrib.markup' in INSTALLED_APPS in your settings.py.
-You will then need to load the markup module in a template:
-
- {% load markup %}
-
-After that, you should be able to use markdown filter in that template
-as follows by putting "|markdown" after a variable, e.g.:
-
- {{ post.body|markdown }}
-
-If you want to use markdown with extensions or want an option of
-disabling HTML (e.g., in comments) edit
-django/contrib/markup/templatetags/markup.py file in your django tree
-replacing the definition of markdown() function with the following:
-
- def markdown(value, arg=''):
-
- try:
- import markdown
- except ImportError:
- if settings.DEBUG:
- raise (template.TemplateSyntaxError,
- "Error in {% markdown %} filter: "
- + "The markdown library isn't installed.")
- else :
- from django.utils.html import escape, linebreaks
- return linebreaks(escape(value))
- else:
- extensions=arg.split(",")
- if len(extensions) > 0 and extensions[0] == "safe" :
- extensions = extensions[1:]
- safe_mode = True
- else :
- safe_mode = False
- return markdown.markdown(value, extensions, safe_mode=safe_mode)
-
-(This code snippet has been adapted from one proposed by [Waylan
-Limberg](http://achinghead.com/).)
-
-You should then be able to load extensions by listing them in quotes
-separated by comas:
-
- {{ post.body|markdown:"imagelinks,footnotes" }}
-
-If you want to disable HTML, include "safe" as the first argument:
-
- {{ post.body|markdown:"safe" }}
-
-<a name="Credits"></a>
-<h3 class="title">Credits</h3>
-
-* The first version of this script was written by [Manfred
- Stienstra](http://www.dwerg.net/), who is responsible for about
- a quarter of the code.
-* Daniel Krech provided the setup.py script.
-* G. Clark Haynes submitted a patch for indented lists.
-* Tiago Cogumbreiro submitted an email autolink fix.
-* Sergej Chodarev submitted a patch for treatment of `<hr/>` tags.
-* Chris Clark submitted a patch to handle `<mailto:...>` syntax and a reg ex for "smart" emphasis (ignoring underscores within a word).
-* Steward Midwinter wrote command-line parser and cleaned up comments.
-* Many other people helped by reporting bugs.
-
-<a name="License"></a>
-<h3 class="title">License</h3>
-
-The code is dual-licensed under
-[GPL](http://www.gnu.org/copyleft/gpl.html) and [BSD
-License](http://www.opensource.org/licenses/bsd-license.php). Other
-licensing arrangements can be discussed.
-
-<a name="Contact"></a>
-<h3 class="title">Contact Info</h3>
-
-Email qaramazov [at] gmail.com if you have any questions or spot any
-bugs. (Feel free to write in English, Russian, Portuguese or
-Spanish.)
-
-Or subscribe to [python-markdown-discuss](http://lists.sourceforge.net/lists/listinfo/python-markdown-discuss).
-
-
-<a name="Change"></a>
-<h3 class="title">Recent Changes</h3>
-
-Oct 11, 2006: Releasing v. 1.6 with a whole bunch of changes (since
-May 15), including:
-
-- Fixed a bug that caused some text to be lost after comments.
-- Added exception for PHP tags when handling html blocks.
-- Incorporated Sergej Chodarev's patch to fix a problem with ampersand
- normalization and html blocks.
-- Switched to using optparse. Added proper support for unicode.
-- Fixed the <!--@address.com> problem (Tracker #1501354).
-- Stopped catching unquoted titles in reference links. Stopped
- creating blank headers.
-
-May 15, 2006: A bug with lists, recursion on block-level elements,
-run-in headers, spaces before headers, unicode input (thanks to Aaron
-Swartz). Sourceforge tracker #s: 1489313, 1489312, 1489311, 1488370,
-1485178, 1485176. (v. 1.5)
-
-Mar. 24, 2006: Switched to a not-so-recursive algorithm with
-_handleInline. (v. 1.4)
-
-For a full list of changes see CHANGE_LOG.txt in the current version
-of markdown.
-
-<?php include("markdown-footer.php"); ?>
diff --git a/sidebar.txt b/sidebar.txt
deleted file mode 100644
index 6ac3253..0000000
--- a/sidebar.txt
+++ /dev/null
@@ -1,37 +0,0 @@
-SourceForge</p>
-
-* [Download](http://sourceforge.net/project/showfiles.php?group_id=153041)
-* [Report a Bug](http://sourceforge.net/tracker/?func=add&group_id=153041&atid=790198)
-* [Mailing List](http://lists.sourceforge.net/lists/listinfo/python-markdown-discuss)
-* [Subversion](http://sourceforge.net/svn/?group_id=153041)
-
-This Page
-
-* [Summary](index.php#Summary)
-* [Installation](index.php#Installation)
-* [Command Line Usage](index.php#Commandline)
-* [Using the Module](index.php#Module)
-* [Extending](index.php#Extending)
-* [Using Markdown with Django](index.php#Django)
-* [License](index.php#License)
-* [Contact Info](index.php#Contact)
-* [Credits](index.php#Credits)
-* [Change Log](index.php#Change)
-* [RSS/XML](news.rss)
-
-Extensions
-
-* [Table of Contents](extensions/markdown_with_toc.py)
-* [WikiLinks](http://achinghead.com/archives/67/adding-wikilinks-to-markdown-in-python/)
-* [Python Code Highlighting](http://www.lethalman.net/2006/03/11/markdown-extension-to-highlight-python-code/)
-* [Simple Tables](http://k7a.org/tables_python_markdown/)
-
-Integration
-
-* [with MoinMoin](http://wiki.vja2.net/MyMoinPlugins)
-* [with Django](http://achinghead.com/archives/70/django-blog-and-markdown/) (also [here](http://www.postneo.com/2005/08/10/django-markup-template-tags))
-*
-
-Related Projects
-
-* [mkdn2latex](http://www.thefactz.org/archives/144) - convert Markdown to Latex \ No newline at end of file