diff options
| -rw-r--r-- | home_page.txt | 245 |
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"); ?> |