From 700a210c5a343eebdd8cf930276be09c5e5af5b5 Mon Sep 17 00:00:00 2001 From: Yuri Takhteyev Date: Thu, 12 Oct 2006 04:36:27 +0000 Subject: v 1.6 --- home_page.txt | 245 ++++++++++++++++++++++++++++++++++++++-------------------- 1 file 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)). - - +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. -

Installation and Usage

+

Installation

+ +[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. + +

Command Line Usage

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 + python markdown.py > -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 +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=~~~~~~~~)" + + +

Using the Module

+ +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() + + -

Extending

+

Writing Extensions

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)

Credits

@@ -137,62 +251,29 @@ Or subscribe to [python-markdown-discuss](http://lists.sourceforge.net/lists/lis -

Change Log

- -*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 `
` 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 -`
` to `
`. (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 `
`.  Made "\Recent Changes
+
+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