aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--home_page.txt245
1 files changed, 163 insertions, 82 deletions
diff --git a/home_page.txt b/home_page.txt
index d24c176..9054254 100644
--- a/home_page.txt
+++ b/home_page.txt
@@ -12,21 +12,23 @@ 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 to on. (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.)-->
+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 and Usage</h3>
+<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 "python setup.py install"
+from a directory where you unzip the files.
-If you want to install the module into your python tree, get
-[setup.py](setup.py) and run "python setup.py install" from a
-directory where you put markdown.py.
+<a name="Commandline"></a>
+<h3 class="title">Command Line Usage</h3>
To use markdown.py by itself, run it as
@@ -34,19 +36,75 @@ To use markdown.py by itself, run it as
or
- python markdown.py <input_file> <output_file>
+ python markdown.py <input_file> > <output_file>
-To get footnotes, add a "-footnotes" option:
+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
+ --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
- python markdown.py -footnotes <input_file> <output_file>
+If the extension supports config options (see below), you can also
+pass them in as well:
-To use it as a module:
+ python markdown.py -x "footnotes(PLACE_MARKER=~~~~~~~~)"
+
+<a name="Module"></a>
+<h3 class="title">Using the Module</h3>
+
+To use it as 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')
+
+ return md.toString()
+
+or, if you want to process multiple strings:
+
+ md = Markdown(text=None)
+ md.toString(text)
+
+Finally, if the extensions are fully compatible, you should be able to
+get a list of extensions and their config parameters:
+
+ for x in md.getExtensions():
+
+ print x.name
+ print x.oneliner
+ print x.getConfigInfo()
+
+
<a name="Extending"></a>
-<h3 class="title">Extending</h3>
+<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
@@ -54,26 +112,26 @@ 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.
-
+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 :
+ 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
+ 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.
+document. Postprocessor classes must extend markdown.Postprocessor.
- class SamplePostprocessor :
+ class SamplePostprocessor (markdown.Postprocessor):
def run(self, doc) :
doc.documentElement.appendChild(doc.createElement("new"))
@@ -84,7 +142,7 @@ 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 (BasePattern) :
+ class MyCustomPattern (markdown.Pattern) :
def handleMatch(self, m, doc) :
el = doc.createElement('custom')
el.setAttribute('stuff', m.group(3))
@@ -93,7 +151,55 @@ object into a DOM fragment
new_pattern = MyCustomPattern(r'your regular expression here')
md_instance.inlinePatterns.insert(SOME_INDEX, new_pattern)
-See the implementation of footnote support inside markdown.py for an
+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 (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
@@ -102,7 +208,15 @@ footnotes at the end of the document)
Other extensions:
-* [Table-of-contents extension](extensions/markdown_with_toc.py) by Chris Clark (inserts a "title" element and a table of contents).
+* [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="Credits"></a>
<h3 class="title">Credits</h3>
@@ -137,62 +251,29 @@ Or subscribe to [python-markdown-discuss](http://lists.sourceforge.net/lists/lis
<a name="Change"></a>
-<h3 class="title">Change Log</h3>
-
-*Feb. 28, 2006:* Clean-up and command-line handling by Stewart
-Midwinter. ([version 1.3](markdown-1.3.py))
-
-*Feb. 24, 2006:* Fixed a bug with the last line of the list appearing
-again as a separate paragraph. Incorporated Chris Clark's "mailto"
-patch. Added support for `<br />` at the end of lines ending in two or
-more spaces. Fixed a crashing bug when using ImageReferencePattern.
-Added "hr" and "hr/" to BLOCK\_LEVEL\_ELEMENTS and changed
-`<hr/>` to `<hr />`. (Thanks to Sergej Chodarev.)
-Added several utility methods to Nanodom.
-([version 1.2](markdown-1.2.py))
-
-*Nov. 30, 2005:* Fixed a bug with certain tabbed lines inside lists
-getting wrapped in `<pre><code>`. Made "\<!...", "\<?...", etc. behave
-like block-level HTML tags. ([version 1.1](markdown-1.1.py))
-
-*Nov. 14, 2005:* Added entity code and email autolink fix by Tiago
-Cogumbreiro. Fixed some small issues with backticks to get 100
-compliance with John's test suite. Added an unlink method for
-documents to aid with memory collection (per Doug Sauder's
-suggestion). Restricted a set of html tags that get treated as
-block-level elements. ([version 1.0](markdown-1.0.py))
-
-*Sept. 18, 2005:* Refactored the whole script to make it easier to
-customize it and made footnote functionality into an extension.
-([version 0.9](markdown-0.9.py))
-
-*Sept. 5, 2005:* Fixed a bug with multi-paragraph footnotes. Added
-attribute support.
-
-*Sept. 1, 2005:* Changed the way headers are handled to allow inline
-syntax in headers (e.g. links) and got the lists to use p-tags
-correctly. ([version 0.8](markdown-0.8.py))
-
-*Aug. 29, 2005:* Added flexible tabs, fixed a few small issues, added
-basic support for footnotes, got rid of xml.dom.minidom and added
-pretty-printing. ([version 0.7](markdown-0.7.py))
-
-*Aug. 13, 2005:* Fixed a number of small bugs in order to conform to
-the test suite. ([version 0.6](markdown-0.6.py))
-
-*Aug. 11, 2005:* Added support for inline html and entities, inline
-images, autolinks, underscore emphasis. Cleaned up and refactored the
-code, added some more comments. ([version 0.5](markdown-0.5.py))
-
-*Feb. 19, 2005:* Rewrote the handling of high-level elements to allow
-multi-line list items and all sorts of nesting. ([version 0.4](markdown-0.4.py))
-
-*Feb. 3, 2005:* Reference-style links, single-line lists, backticks,
-escape, emphasis in the beginning of the paragraph.
-
-*Nov. 2004:* Added links, block quotes, html blocks to Manfred Stienstra's code.
-
-
-
+<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"); ?>