diff options
Diffstat (limited to 'docs')
28 files changed, 441 insertions, 429 deletions
diff --git a/docs/authors.txt b/docs/authors.txt index 53eaaba..84c69d0 100644 --- a/docs/authors.txt +++ b/docs/authors.txt @@ -9,15 +9,15 @@ Primary Authors [Yuri Takteyev](http://freewisdom.org/) -: Yuri has written much of the current code while procrastingating his Ph.D. +: Yuri has written much of the current code while procrastinating his Ph.D. [Waylan Limberg](http://achinghead.com/) : Waylan is the current maintainer of the code and has written much the current code base, included a complete refactor of the core. He started out by - authoring mmany of the available extensions and later was asked to join Yuri, - where he began fixing nummrious bugs, adding documentation and making general - improvements to the existing codebase. + authoring many of the available extensions and later was asked to join Yuri, + where he began fixing numerous bugs, adding documentation and making general + improvements to the existing code base. Artem Yunusov @@ -28,7 +28,7 @@ Artem Yunusov [Manfed Stienstra](http://www.dwerg.net/) : Manfed wrote the original version of the script and is responsible for - various parts of the existing codebase. + various parts of the existing code base. David Wolever @@ -40,7 +40,7 @@ Other Contributors The incomplete list of individuals below have provided patches or otherwise contributed to the project in various ways. We would like to thank everyone -who has contributed to the progect in any way. +who has contributed to the project in any way. * Eric Abrahamsen * Jeff Balogh diff --git a/docs/change_log.txt b/docs/change_log.txt index e63c48a..9eb2ea8 100644 --- a/docs/change_log.txt +++ b/docs/change_log.txt @@ -4,20 +4,20 @@ prev_url: test_suite.html next_title: Release Notes for v2.6 next_url: release-2.6.html -Python-Markdown Changelog +Python-Markdown Change Log ========================= ____________: Released version 2.6 ([Notes](release-2.6.html)). -Nov 19, 2014: Released version 2.5.2 (a bugfix release). +Nov 19, 2014: Released version 2.5.2 (a bug-fix release). -Sept 26, 2014: Released version 2.5.1 (a bugfix release). +Sept 26, 2014: Released version 2.5.1 (a bug-fix release). Sept 12, 2014: Released version 2.5.0 ([Notes](release-2.5.html)). Feb 16, 2014: Released version 2.4.0 ([Notes](release-2.4.html)). -Mar 22, 2013: Released version 2.3.1 (a bugfix release). +Mar 22, 2013: Released version 2.3.1 (a bug-fix release). Mar 14, 2013: Released version 2.3.0 ([Notes](release-2.3.html)) @@ -43,24 +43,24 @@ Feb 2009: Added support for multi-level lists to new Blockprocessors. Jan 2009: Added HTML 4 output as an option (thanks Eric Abrahamsen) -Nov 2008: Added Definistion List ext. Replaced old core with BlockProcessors. +Nov 2008: Added Definition List ext. Replaced old core with Blockprocessors. Broken up into multiple files. Oct 2008: Changed logging behavior to work better with other systems. -Refactored tree tarversing. Added treap implementation, then replaced with -OrderedDEict. Renamed various processors to better reflect what they actually -do. Refactored footnote ext to match php Extra's output. +Refactored tree traversing. Added `treap` implementation, then replaced with +OrderedDict. Renamed various processors to better reflect what they actually +do. Refactored footnote ext to match PHP Extra's output. -Sept 2008: Moved prettifyTree to a Postprocessor, replaced wikilink ext -with wikilinks (note the s) ext (uses bracketed links instead of CamelCase) +Sept 2008: Moved `prettifyTree` to a Postprocessor, replaced WikiLink ext +with WikiLinks (note the s) ext (uses bracketed links instead of CamelCase) and various bug fixes. -August 18 2008: Reorganized directory structure. Added a 'docs' dir +August 18 2008: Reorganized directory structure. Added a 'docs' directory and moved all extensions into a 'markdown-extensions' package. Added additional documentation and a few bug fixes. (v2.0-beta) August 4 2008: Updated included extensions to ElementTree. Added a -seperate commanline script. (v2.0-alpha) +separate command line script. (v2.0-alpha) July 2008: Switched from home-grown NanoDOM to ElementTree and various related bugs (thanks Artem Yunusov). @@ -69,24 +69,24 @@ June 2008: Fixed issues with nested inline patterns and cleaned up testing framework (thanks Artem Yunusov). May 2008: Added a number of additional extensions to the -distribution and other minor changes. Moved repo to git from svn. +distribution and other minor changes. Moved repository to git from svn. -Mar 2008: Refactored extension api to accept either an +Mar 2008: Refactored extension API to accept either an extension name (as a string) or an instance of an extension (Thanks David Wolever). Fixed various bugs and added doc strings. -Feb 2008: Various bugfixes mostly regarding extensions. +Feb 2008: Various bug-fixes mostly regarding extensions. Feb 18, 2008: Version 1.7. Feb 13, 2008: A little code cleanup and better documentation -and inheritance for pre/post proccessors. +and inheritance for Preprocessors/Postprocessors. -Feb 9, 2008: Doublequotes no longer html escaped and rawhtml +Feb 9, 2008: Double-quotes no longer HTML escaped and raw HTML honors `<?foo>`, `<@foo>`, and `<%foo>` for those who run markdown on template syntax. -Dec 12, 2007: Updated docs. Removed encoding arg from Markdown +Dec 12, 2007: Updated docs. Removed encoding argument from Markdown and markdown as per list discussion. Clean up in prep for 1.7. Nov 29, 2007: Added support for images inside links. Also fixed @@ -96,39 +96,39 @@ Nov 19, 2007: `message` now uses python's logging module. Also removed limit imposed by recursion in `_process_section()`. You can now parse as long of a document as your memory can handle. -Nov 5, 2007: Moved safe_mode code to a textPostprocessor and added +Nov 5, 2007: Moved `safe_mode` code to a `textPostprocessor` and added escaping option. Nov 3, 2007: Fixed convert method to accept empty strings. -Oct 30, 2007: Fixed BOM removal (thanks Malcolm Tredinnick). Fixed -infinite loop in bracket regex for inline links. +Oct 30, 2007: Fixed `BOM` removal (thanks Malcolm Tredinnick). Fixed +infinite loop in bracket regular expression for inline links. -Oct 11, 2007: LineBreaks is now an inlinePattern. Fixed HR in -blockquotes. Refactored _processSection method (see tracker #1793419). +Oct 11, 2007: `LineBreaks` is now an `inlinePattern`. Fixed `HR` in +blockquotes. Refactored `_processSection` method (see tracker #1793419). -Oct 9, 2007: Added textPreprocessor (from 1.6b). +Oct 9, 2007: Added `textPreprocessor` (from 1.6b). Oct 8, 2008: Fixed Lazy Blockquote. Fixed code block on first line. Fixed empty inline image link. -Oct 7, 2007: Limit recursion on inlinePatterns. Added a 'safe' tag -to htmlStash. +Oct 7, 2007: Limit recursion on inline patterns. Added a 'safe' tag +to `htmlStash`. March 18, 2007: Fixed or merged a bunch of minor bugs, including multi-line comments and markup inside links. (Tracker #s: 1683066, 1671153, 1661751, 1627935, 1544371, 1458139.) -> v. 1.6b Oct 10, 2006: Fixed a bug that caused some text to be lost after -comments. Added "safe mode" (user's html tags are removed). +comments. Added "safe mode" (user's HTML tags are removed). -Sept 6, 2006: Added exception for PHP tags when handling html blocks. +Sept 6, 2006: Added exception for PHP tags when handling HTML blocks. August 7, 2006: Incorporated Sergej Chodarev's patch to fix a problem -with ampersand normalization and html blocks. +with ampersand normalization and HTML blocks. -July 10, 2006: Switched to using optparse. Added proper support for -unicode. +July 10, 2006: Switched to using `optparse`. Added proper support for +Unicode. July 9, 2006: Fixed the `<!--@address.com>` problem (Tracker #1501354). @@ -136,25 +136,25 @@ May 18, 2006: 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 +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. (Version 1.4) +`_handleInline`. (Version 1.4) Mar. 15, 2006: Replaced some instance variables with class variables (a patch from Stelios Xanthakis). Chris Clark's new regexps that do -not trigger midword underlining. +not trigger mid-word underlining. Feb. 28, 2006: Clean-up and command-line handling by Stewart Midwinter. (Version 1.3) Feb. 24, 2006: Fixed a bug with the last line of the list appearing -again as a separate paragraph. Incorporated Chris Clark's "mailto" +again as a separate paragraph. Incorporated Chris Clark's "mail-to" patch. Added support for `<br />` at the end of lines ending in two or -more spaces. Fixed a crashing bug when using ImageReferencePattern. -Added several utility methods to Nanodom. (Version 1.2) +more spaces. Fixed a crashing bug when using `ImageReferencePattern`. +Added several utility methods to `Nanodom`. (Version 1.2) Jan. 31, 2006: Added `hr` and `hr/` to BLOCK_LEVEL_ELEMENTS and changed `<hr/>` to `<hr />`. (Thanks to Sergej Chodarev.) @@ -165,14 +165,14 @@ getting wrapped in `<pre><code>`. (v. 1.1) Nov. 19, 2005: Made `<!...`, `<?...`, etc. behave like block-level HTML tags. -Nov. 14, 2005: Added entity code and email autolink fix by Tiago +Nov. 14, 2005: Added entity code and email auto-link fix by Tiago Cogumbreiro. Fixed some small issues with backticks to get 100% compliance with John's test suite. (v. 1.0) -Nov. 7, 2005: Added an unlink method for documents to aid with memory +Nov. 7, 2005: Added an `unlink` method for documents to aid with memory collection (per Doug Sauder's suggestion). -Oct. 29, 2005: Restricted a set of html tags that get treated as +Oct. 29, 2005: Restricted a set of HTML tags that get treated as block-level elements. Sept. 18, 2005: Refactored the whole script to make it easier to @@ -193,8 +193,8 @@ pretty-printing. (v. 0.7) Aug. 13, 2005: Fixed a number of small bugs in order to conform to the test suite. (v. 0.6) -Aug. 11, 2005: Added support for inline html and entities, inline -images, autolinks, underscore emphasis. Cleaned up and refactored the +Aug. 11, 2005: Added support for inline HTML and entities, inline +images, auto-links, underscore emphasis. Cleaned up and refactored the code, added some more comments. Feb. 19, 2005: Rewrote the handling of high-level elements to allow @@ -203,7 +203,7 @@ multi-line list items and all sorts of nesting. Feb. 3, 2005: Reference-style links, single-line lists, backticks, escape, emphasis in the beginning of the paragraph. -Nov. 2004: Added links, blockquotes, html blocks to Manfred +Nov. 2004: Added links, blockquotes, HTML blocks to Manfred Stienstra's code Apr. 2004: Manfred's version at <http://www.dwerg.net/projects/markdown/> diff --git a/docs/cli.txt b/docs/cli.txt index 5098771..c2b37e4 100644 --- a/docs/cli.txt +++ b/docs/cli.txt @@ -23,18 +23,18 @@ following format: $ python -m markdown [options] [args] -That will run the module as a script with the options and args provided. +That will run the module as a script with the options and arguments provided. At its most basic usage, one would simply pass in a file name as the only argument: $ python -m markdown input_file.txt -Piping input and output (on STDIN and STDOUT) is fully supported as well. +Piping input and output (on `STDIN` and `STDOUT`) is fully supported as well. For example: $ echo "Some **Markdown** text." | python -m markdown > output.html -Use the `--help` option for a list all available options and args: +Use the `--help` option for a list all available options and arguments: $ python -m markdown --help @@ -44,7 +44,7 @@ follow the instructions below to use a wrapper script: Setup ----- -Upon installation, the ``markdown_py`` script will have been copied to +Upon installation, the `markdown_py` script will have been copied to your Python "Scripts" directory. Different systems require different methods to ensure that any files in the Python "Scripts" directory are on your system path. @@ -52,11 +52,11 @@ path. * **Windows**: Assuming a default install of Python on Windows, your "Scripts" directory - is most likely something like ``C:\\Python26\Scripts``. Verify the location + is most likely something like `C:\\Python26\Scripts`. Verify the location of your "Scripts" directory and add it to you system path. - Calling ``markdown_py`` from the command line will call the wrapper batch - file ``markdown_py.bat`` in the "Scripts" directory created during install. + Calling `markdown_py` from the command line will call the wrapper batch + file `markdown_py.bat` in the `"Scripts"` directory created during install. * __*nix__ (Linux, OSX, BSD, Unix, etc.): @@ -64,33 +64,33 @@ path. of them here, we'll provide a few helpful pointers: * Some systems will automatically install the script on your path. Try it - and see if it works. Just run ``markdown_py`` from the command line. + and see if it works. Just run `markdown_py` from the command line. * Other systems may maintain a separate "Scripts" ("bin") directory which you need to add to your path. Find it (check with your distribution) and either add it to your path or make a symbolic link to it from your path. - * If you are sure ``markdown_py`` is on your path, but it still isn't being + * If you are sure `markdown_py` is on your path, but it still is not being found, check the permissions of the file and make sure it is executable. - As an alternative, you could just ``cd`` into the directory which contains + As an alternative, you could just `cd` into the directory which contains the source distribution, and run it from there. However, remember that your markdown text files will not likely be in that directory, so it is much - more convenient to have ``markdown_py`` on your path. + more convenient to have `markdown_py` on your path. !!!Note - Python-Markdown uses "markdown_py" as a script name because + Python-Markdown uses `"markdown_py"` as a script name because the Perl implementation has already taken the more obvious name "markdown". Additionally, the default Python configuration on some systems would cause a - script named "markdown.py" to fail by importing itself rather than the markdown - library. Therefore, the script has been named "markdown_py" as a compromise. If + script named `"markdown.py"` to fail by importing itself rather than the markdown + library. Therefore, the script has been named `"markdown_py"` as a compromise. If you prefer a different name for the script on your system, it is suggested that you create a symbolic link to `markdown_py` with your preferred name. Usage ----- -To use ``markdown_py`` from the command line, run it as +To use `markdown_py` from the command line, run it as $ markdown_py input_file.txt @@ -133,15 +133,15 @@ above example might look like this: UNIQUE_IDS: True Note that while the `--extension_configs` option does specify the "markdown.extensions.footnotes" -extension, you still need to load the extension with the `-x` option, or the configs for that +extension, you still need to load the extension with the `-x` option, or the configuration for that extension will be ignored. -The `--extension_configs` option will only support YAML config files if [PyYaml] is +The `--extension_configs` option will only support YAML configuration files if [PyYAML] is installed on your system. JSON should work with no additional dependencies. The format -of your config file is automatically detected. +of your configuration file is automatically detected. !!!warning - The previously documented method of appending the extension configs as a string to the + The previously documented method of appending the extension configuration options as a string to the extension name will be deprecated in Python-Markdown version 2.6. The `--extension_configs` option should be used instead. See the [2.5 release notes] for more information. diff --git a/docs/extensions/admonition.txt b/docs/extensions/admonition.txt index fcf866b..d68bd5d 100644 --- a/docs/extensions/admonition.txt +++ b/docs/extensions/admonition.txt @@ -26,7 +26,7 @@ Admonitions are created using the following syntax: This is the second paragraph. -`type` will be used as the CSS classname and as default title. It must be a +`type` will be used as the CSS class name and as default title. It must be a single word. So, for instance: !!! note diff --git a/docs/extensions/api.txt b/docs/extensions/api.txt index 7987c25..66daa86 100644 --- a/docs/extensions/api.txt +++ b/docs/extensions/api.txt @@ -8,14 +8,14 @@ Writing Extensions for Python-Markdown ====================================== Python-Markdown includes an API for extension writers to plug their own -custom functionality and/or syntax into the parser. There are preprocessors +custom functionality and/or syntax into the parser. There are Preprocessors which allow you to alter the source before it is passed to the parser, inline patterns which allow you to add, remove or override the syntax of -any inline elements, and postprocessors which allow munging of the +any inline elements, and Postprocessors which allow munging of the output of the parser before it is returned. If you really want to dive in, -there are also blockprocessors which are part of the core BlockParser. +there are also Blockprocessors which are part of the core BlockParser. -As the parser builds an [ElementTree][] object which is later rendered +As the parser builds an [ElementTree][ElementTree] object which is later rendered as Unicode text, there are also some helpers provided to ease manipulation of the tree. Each part of the API is discussed in its respective section below. Additionally, reading the source of some [Available Extensions][] may be @@ -29,10 +29,10 @@ Preprocessors munge the source text before it is passed into the Markdown core. This is an excellent place to clean up bad syntax, extract things the parser may otherwise choke on and perhaps even store it for later retrieval. -Preprocessors should inherit from ``markdown.preprocessors.Preprocessor`` and -implement a ``run`` method with one argument ``lines``. The ``run`` method of +Preprocessors should inherit from `markdown.preprocessors.Preprocessor` and +implement a `run` method with one argument `lines`. The `run` method of each Preprocessor will be passed the entire source text as a list of Unicode -strings. Each string will contain one line of text. The ``run`` method should +strings. Each string will contain one line of text. The `run` method should return either that list, or an altered list of Unicode strings. A pseudo example: @@ -54,27 +54,27 @@ Inline Patterns {: #inlinepatterns } ------------------------------------ Inline Patterns implement the inline HTML element syntax for Markdown such as -``*emphasis*`` or ``[links](http://example.com)``. Pattern objects should be -instances of classes that inherit from ``markdown.inlinepatterns.Pattern`` or +`*emphasis*` or `[links](http://example.com)`. Pattern objects should be +instances of classes that inherit from `markdown.inlinepatterns.Pattern` or one of its children. Each pattern object uses a single regular expression and must have the following methods: -* **``getCompiledRegExp()``**: +* **`getCompiledRegExp()`**: Returns a compiled regular expression. -* **``handleMatch(m)``**: +* **`handleMatch(m)`**: Accepts a match object and returns an ElementTree element of a plain Unicode string. -Note that any regular expression returned by ``getCompiledRegExp`` must capture -the whole block. Therefore, they should all start with ``r'^(.*?)'`` and end -with ``r'(.*?)!'``. When using the default ``getCompiledRegExp()`` method -provided in the ``Pattern`` you can pass in a regular expression without that -and ``getCompiledRegExp`` will wrap your expression for you and set the +Note that any regular expression returned by `getCompiledRegExp` must capture +the whole block. Therefore, they should all start with `r'^(.*?)'` and end +with `r'(.*?)!'`. When using the default `getCompiledRegExp()` method +provided in the `Pattern` you can pass in a regular expression without that +and `getCompiledRegExp` will wrap your expression for you and set the `re.DOTALL` and `re.UNICODE` flags. This means that the first group of your -match will be ``m.group(2)`` as ``m.group(1)`` will match everything before the +match will be `m.group(2)` as `m.group(1)` will match everything before the pattern. For an example, consider this simplified emphasis pattern: @@ -103,23 +103,24 @@ that example pattern is not very DRY. A pattern for `**strong**` text would be almost identical, with the exception that it would create a 'strong' element. Therefore, Markdown provides a number of generic pattern classes that can provide some common functionality. For example, both emphasis and strong are -implemented with separate instances of the ``SimpleTagPattern`` listed below. -Feel free to use or extend any of the Pattern classes found at `markdown.inlinepatterns`. +implemented with separate instances of the `SimpleTagPattern` listed below. +Feel free to use or extend any of the Pattern classes found at +`markdown.inlinepatterns`. **Generic Pattern Classes** -* **``SimpleTextPattern(pattern)``**: +* **`SimpleTextPattern(pattern)`**: - Returns simple text of ``group(2)`` of a ``pattern``. + Returns simple text of `group(2)` of a `pattern`. -* **``SimpleTagPattern(pattern, tag)``**: +* **`SimpleTagPattern(pattern, tag)`**: - Returns an element of type "`tag`" with a text attribute of ``group(3)`` - of a ``pattern``. ``tag`` should be a string of a HTML element (i.e.: 'em'). + Returns an element of type "`tag`" with a text attribute of `group(3)` + of a `pattern`. `tag` should be a string of a HTML element (i.e.: 'em'). -* **``SubstituteTagPattern(pattern, tag)``**: +* **`SubstituteTagPattern(pattern, tag)`**: - Returns an element of type "`tag`" with no children or text (i.e.: 'br'). + Returns an element of type "`tag`" with no children or text (i.e.: `br`). There may be other Pattern classes in the Markdown source that you could extend or use as well. Read through the source and see if there is anything you can @@ -129,13 +130,13 @@ situation. Treeprocessors {: #treeprocessors } ----------------------------------- -Treeprocessors manipulate an ElemenTree object after it has passed through the +Treeprocessors manipulate an ElementTree object after it has passed through the core BlockParser. This is where additional manipulation of the tree takes place. Additionally, the InlineProcessor is a Treeprocessor which steps through -the tree and runs the InlinePatterns on the text of each Element in the tree. +the tree and runs the Inline Patterns on the text of each Element in the tree. -A Treeprocessor should inherit from ``markdown.treeprocessors.Treeprocessor``, -over-ride the ``run`` method which takes one argument ``root`` (an Elementree +A Treeprocessor should inherit from `markdown.treeprocessors.Treeprocessor`, +over-ride the `run` method which takes one argument `root` (an ElementTree object) and either modifies that root element and returns `None` or returns a new ElementTree object. @@ -148,18 +149,18 @@ A pseudo example: root.text = 'modified content' Note that Python class methods return `None` by default when no `return` -statement is defined. Additionly all Python variables refer to objects by +statement is defined. Additionally all Python variables refer to objects by reference. Therefore, the above `run` method modifies the `root` element in place and returns `None`. The changes made to the `root` element and its children are retained. Some may be inclined to return the modified `root` element. While that would -work, it would cause a copy of the entire ElemetTree to be generated each -time the treeprocessor is run. Therefore, it is generally expected that +work, it would cause a copy of the entire ElementTree to be generated each +time the Treeprocessor is run. Therefore, it is generally expected that the `run` method would only return `None` or a new ElementTree object. For specifics on manipulating the ElementTree, see -[Working with the ElementTree][] below. +[Working with the ElementTree][workingwithetree] below. Postprocessors {: #postprocessors } ----------------------------------- @@ -168,8 +169,8 @@ Postprocessors manipulate the document after the ElementTree has been serialized into a string. Postprocessors should be used to work with the text just before output. -A Postprocessor should inherit from ``markdown.postprocessors.Postprocessor`` -and over-ride the ``run`` method which takes one argument ``text`` and returns +A Postprocessor should inherit from `markdown.postprocessors.Postprocessor` +and over-ride the `run` method which takes one argument `text` and returns a Unicode string. Postprocessors are run after the ElementTree has been serialized back into @@ -185,127 +186,128 @@ contents to a document: BlockParser {: #blockparser } ----------------------------- -Sometimes, pre/tree/postprocessors and Inline Patterns aren't going to do what -you need. Perhaps you want a new type of block type that needs to be integrated -into the core parsing. In such a situation, you can add/change/remove -functionality of the core ``BlockParser``. The BlockParser is composed of a -number of Blockproccessors. The BlockParser steps through each block of text -(split by blank lines) and passes each block to the appropriate Blockprocessor. -That Blockprocessor parses the block and adds it to the ElementTree. The +Sometimes, Preprocessors, Treeprocessors, Postprocessors, and Inline Patterns +are not going to do what you need. Perhaps you want a new type of block type +that needs to be integrated into the core parsing. In such a situation, you can +add/change/remove functionality of the core `BlockParser`. The BlockParser is +composed of a number of Blockprocessors. The BlockParser steps through each +block of text (split by blank lines) and passes each block to the appropriate +Blockprocessor. That Blockprocessor parses the block and adds it to the +ElementTree. The [Definition Lists][] extension would be a good example of an extension that adds/modifies Blockprocessors. -A Blockprocessor should inherit from ``markdown.blockprocessors.BlockProcessor`` -and implement both the ``test`` and ``run`` methods. +A Blockprocessor should inherit from `markdown.blockprocessors.BlockProcessor` +and implement both the `test` and `run` methods. -The ``test`` method is used by BlockParser to identify the type of block. -Therefore the ``test`` method must return a boolean value. If the test returns -``True``, then the BlockParser will call that Blockprocessor's ``run`` method. -If it returns ``False``, the BlockParser will move on to the next -BlockProcessor. +The `test` method is used by BlockParser to identify the type of block. +Therefore the `test` method must return a Boolean value. If the test returns +`True`, then the BlockParser will call that Blockprocessor's `run` method. +If it returns `False`, the BlockParser will move on to the next +Blockprocessor. -The **``test``** method takes two arguments: +The **`test`** method takes two arguments: -* **``parent``**: The parent etree Element of the block. This can be useful as - the block may need to be treated differently if it is inside a list, for +* **`parent`**: The parent ElementTree Element of the block. This can be useful + as the block may need to be treated differently if it is inside a list, for example. -* **``block``**: A string of the current block of text. The test may be a - simple string method (such as ``block.startswith(some_text)``) or a complex +* **`block`**: A string of the current block of text. The test may be a + simple string method (such as `block.startswith(some_text)`) or a complex regular expression. -The **``run``** method takes two arguments: +The **`run`** method takes two arguments: -* **``parent``**: A pointer to the parent etree Element of the block. The run +* **`parent`**: A pointer to the parent ElementTree Element of the block. The run method will most likely attach additional nodes to this parent. Note that - nothing is returned by the method. The Elementree object is altered in place. + nothing is returned by the method. The ElementTree object is altered in place. -* **``blocks``**: A list of all remaining blocks of the document. Your run +* **`blocks`**: A list of all remaining blocks of the document. Your run method must remove (pop) the first block from the list (which it altered in place - not returned) and parse that block. You may find that a block of text legitimately contains multiple block types. Therefore, after processing the first type, your processor can insert the remaining text into the beginning - of the ``blocks`` list for future parsing. + of the `blocks` list for future parsing. Please be aware that a single block can span multiple text blocks. For example, The official Markdown syntax rules state that a blank line does not end a Code Block. If the next block of text is also indented, then it is part of the previous block. Therefore, the BlockParser was specifically designed to -address these types of situations. If you notice the ``CodeBlockProcessor``, -in the core, you will note that it checks the last child of the ``parent``. -If the last child is a code block (``<pre><code>...</code></pre>``), then it +address these types of situations. If you notice the `CodeBlockProcessor`, +in the core, you will note that it checks the last child of the `parent`. +If the last child is a code block (`<pre><code>...</code></pre>`), then it appends that block to the previous code block rather than creating a new code block. -Each BlockProcessor has the following utility methods available: +Each Blockprocessor has the following utility methods available: -* **``lastChild(parent)``**: +* **`lastChild(parent)`**: - Returns the last child of the given etree Element or ``None`` if it had no - children. + Returns the last child of the given ElementTree Element or `None` if it + had no children. -* **``detab(text)``**: +* **`detab(text)`**: Removes one level of indent (four spaces by default) from the front of each line of the given text string. -* **``looseDetab(text, level)``**: +* **`looseDetab(text, level)`**: Removes "level" levels of indent (defaults to 1) from the front of each line of the given text string. However, this methods allows secondary lines to not be indented as does some parts of the Markdown syntax. -Each BlockProcessor also has a pointer to the containing BlockParser instance at -``self.parser``, which can be used to check or alter the state of the parser. -The BlockParser tracks it's state in a stack at ``parser.state``. The state -stack is an instance of the ``State`` class. +Each Blockprocessor also has a pointer to the containing BlockParser instance at +`self.parser`, which can be used to check or alter the state of the parser. +The BlockParser tracks it's state in a stack at `parser.state`. The state +stack is an instance of the `State` class. -**``State``** is a subclass of ``list`` and has the additional methods: +**`State`** is a subclass of `list` and has the additional methods: -* **``set(state)``**: +* **`set(state)`**: - Set a new state to string ``state``. The new state is appended to the end + Set a new state to string `state`. The new state is appended to the end of the stack. -* **``reset()``**: +* **`reset()`**: Step back one step in the stack. The last state at the end is removed from the stack. -* **``isstate(state)``**: +* **`isstate(state)`**: Test that the top (current) level of the stack is of the given string - ``state``. + `state`. -Note that to ensure that the state stack doesn't become corrupted, each time a +Note that to ensure that the state stack does not become corrupted, each time a state is set for a block, that state *must* be reset when the parser finishes parsing that block. -An instance of the **``BlockParser``** is found at ``Markdown.parser``. -``BlockParser`` has the following methods: +An instance of the **`BlockParser`** is found at `Markdown.parser`. +`BlockParser` has the following methods: -* **``parseDocument(lines)``**: +* **`parseDocument(lines)`**: Given a list of lines, an ElementTree object is returned. This should be - passed an entire document and is the only method the ``Markdown`` class + passed an entire document and is the only method the `Markdown` class calls directly. -* **``parseChunk(parent, text)``**: +* **`parseChunk(parent, text)`**: Parses a chunk of markdown text composed of multiple blocks and attaches - those blocks to the ``parent`` Element. The ``parent`` is altered in place + those blocks to the `parent` Element. The `parent` is altered in place and nothing is returned. Extensions would most likely use this method for block parsing. -* **``parseBlocks(parent, blocks)``**: +* **`parseBlocks(parent, blocks)`**: - Parses a list of blocks of text and attaches those blocks to the ``parent`` - Element. The ``parent`` is altered in place and nothing is returned. This + Parses a list of blocks of text and attaches those blocks to the `parent` + Element. The `parent` is altered in place and nothing is returned. This method will generally only be used internally to recursively parse nested blocks of text. While is is not recommended, an extension could subclass or completely replace -the ``BlockParser``. The new class would have to provide the same public API. +the `BlockParser`. The new class would have to provide the same public API. However, be aware that other extensions may expect the core parser provided and will not work with such a drastically different parser. @@ -313,34 +315,34 @@ Working with the ElementTree {: #working_with_et } -------------------------------------------------- As mentioned, the Markdown parser converts a source document to an -[ElementTree][] object before serializing that back to Unicode text. +[ElementTree][ElementTree] object before serializing that back to Unicode text. Markdown has provided some helpers to ease that manipulation within the context of the Markdown module. First, to get access to the ElementTree module import ElementTree from -``markdown`` rather than importing it directly. This will ensure you are using +`markdown` rather than importing it directly. This will ensure you are using the same version of ElementTree as markdown. The module is found at -``markdown.util.etree`` within Markdown. +`markdown.util.etree` within Markdown. from markdown.util import etree -``markdown.util.etree`` tries to import ElementTree from any known location, -first as a standard library module (from ``xml.etree`` in Python 2.5), then as -a third party package (``Elementree``). In each instance, ``cElementTree`` is -tried first, then ``ElementTree`` if the faster C implementation is not +`markdown.util.etree` tries to import ElementTree from any known location, +first as a standard library module (from `xml.etree` in Python 2.5), then as +a third party package (ElementTree). In each instance, `cElementTree` is +tried first, then ElementTree if the faster C implementation is not available on your system. Sometimes you may want text inserted into an element to be parsed by -[InlinePatterns][]. In such a situation, simply insert the text as you normally -would and the text will be automatically run through the InlinePatterns. -However, if you do *not* want some text to be parsed by InlinePatterns, -then insert the text as an ``AtomicString``. +[Inline Patterns][]. In such a situation, simply insert the text as you normally +would and the text will be automatically run through the Inline Patterns. +However, if you do *not* want some text to be parsed by Inline Patterns, +then insert the text as an `AtomicString`. from markdown.util import AtomicString some_element.text = AtomicString(some_text) Here's a basic example which creates an HTML table (note that the contents of -the second cell (``td2``) will be run through InlinePatterns latter): +the second cell (`td2`) will be run through Inline Patterns latter): table = etree.Element("table") table.set("cellpadding", "2") # Set cellpadding to 2 @@ -352,7 +354,7 @@ the second cell (``td2``) will be run through InlinePatterns latter): table.tail = "Text after table" # Add text after table You can also manipulate an existing tree. Consider the following example which -adds a ``class`` attribute to ``<a>`` elements: +adds a `class` attribute to `<a>` elements: def set_link_class(self, element): for child in element: @@ -369,53 +371,53 @@ Integrating Your Code Into Markdown {: #integrating_into_markdown } Once you have the various pieces of your extension built, you need to tell Markdown about them and ensure that they are run in the proper sequence. -Markdown accepts an ``Extension`` instance for each extension. Therefore, you -will need to define a class that extends ``markdown.extensions.Extension`` and -over-rides the ``extendMarkdown`` method. Within this class you will manage +Markdown accepts an `Extension` instance for each extension. Therefore, you +will need to define a class that extends `markdown.extensions.Extension` and +over-rides the `extendMarkdown` method. Within this class you will manage configuration options for your extension and attach the various processors and patterns to the Markdown instance. It is important to note that the order of the various processors and patterns -matters. For example, if we replace ``http://...`` links with ``<a>`` elements, -and *then* try to deal with inline html, we will end up with a mess. +matters. For example, if we replace `http://...` links with `<a>` elements, +and *then* try to deal with inline HTML, we will end up with a mess. Therefore, the various types of processors and patterns are stored within an -instance of the Markdown class in [OrderedDict][]s. Your ``Extension`` class +instance of the Markdown class in [OrderedDict][]s. Your `Extension` class will need to manipulate those OrderedDicts appropriately. You may insert instances of your processors and patterns into the appropriate location in an OrderedDict, remove a built-in instance, or replace a built-in instance with your own. -### extendMarkdown {: #extendmarkdown } +### `extendMarkdown` {: #extendmarkdown } -The ``extendMarkdown`` method of a ``markdown.extensions.Extension`` class +The `extendMarkdown` method of a `markdown.extensions.Extension` class accepts two arguments: -* **``md``**: +* **`md`**: A pointer to the instance of the Markdown class. You should use this to access the [OrderedDict][]s of processors and patterns. They are found under the following attributes: - * ``md.preprocessors`` - * ``md.inlinePatterns`` - * ``md.parser.blockprocessors`` - * ``md.treeprocessors`` - * ``md.postprocessors`` + * `md.preprocessors` + * `md.inlinePatterns` + * `md.parser.blockprocessors` + * `md.treeprocessors` + * `md.postprocessors` Some other things you may want to access in the markdown instance are: - * ``md.htmlStash`` - * ``md.output_formats`` - * ``md.set_output_format()`` - * ``md.output_format`` - * ``md.serializer`` - * ``md.registerExtension()`` - * ``md.html_replacement_text`` - * ``md.tab_length`` - * ``md.enable_attributes`` - * ``md.smart_emphasis`` + * `md.htmlStash` + * `md.output_formats` + * `md.set_output_format()` + * `md.output_format` + * `md.serializer` + * `md.registerExtension()` + * `md.html_replacement_text` + * `md.tab_length` + * `md.enable_attributes` + * `md.smart_emphasis` -* **``md_globals``**: +* **`md_globals`**: Contains all the various global variables within the markdown module. @@ -447,32 +449,32 @@ in a specific location in relation to the existing items. Think of OrderedDict as a combination of a list and a dictionary as it has methods common to both. For example, you can get and set items using the -``od[key] = value`` syntax and the methods ``keys()``, ``values()``, and -``items()`` work as expected with the keys, values and items returned in the -proper order. At the same time, you can use ``insert()``, ``append()``, and -``index()`` as you would with a list. +`od[key] = value` syntax and the methods `keys()`, `values()`, and +`items()` work as expected with the keys, values and items returned in the +proper order. At the same time, you can use `insert()`, `append()`, and +`index()` as you would with a list. Generally speaking, within Markdown extensions you will be using the special -helper method ``add()`` to add additional items to an existing OrderedDict. +helper method `add()` to add additional items to an existing OrderedDict. -The ``add()`` method accepts three arguments: +The `add()` method accepts three arguments: -* **``key``**: A string. The key is used for later reference to the item. +* **`key`**: A string. The key is used for later reference to the item. -* **``value``**: The object instance stored in this item. +* **`value`**: The object instance stored in this item. -* **``location``**: Optional. The items location in relation to other items. +* **`location`**: Optional. The items location in relation to other items. Note that the location can consist of a few different values: - * The special strings ``"_begin"`` and ``"_end"`` insert that item at the + * The special strings `"_begin"` and `"_end"` insert that item at the beginning or end of the OrderedDict respectively. - * A less-than sign (``<``) followed by an existing key (i.e.: - ``"<somekey"``) inserts that item before the existing key. + * A less-than sign (`<`) followed by an existing key (i.e.: + `"<somekey"`) inserts that item before the existing key. - * A greater-than sign (``>``) followed by an existing key (i.e.: - ``">somekey"``) inserts that item after the existing key. + * A greater-than sign (`>`) followed by an existing key (i.e.: + `">somekey"`) inserts that item after the existing key. Consider the following example: @@ -485,8 +487,8 @@ Consider the following example: [("one", 1), ("three", 3), ("four", 4)] Note that when building an OrderedDict in order, the extra features of the -``add`` method offer no real value and are not necessary. However, when -manipulating an existing OrderedDict, ``add`` can be very helpful. So let's +`add` method offer no real value and are not necessary. However, when +manipulating an existing OrderedDict, `add` can be very helpful. So let's insert another item into the OrderedDict. >>> od.add('two', 2, '>one') # Insert after 'one' @@ -495,16 +497,16 @@ insert another item into the OrderedDict. Now let's insert another item. - >>> od.add('twohalf', 2.5, '<three') # Insert before 'three' + >>> od.add('two-point-five', 2.5, '<three') # Insert before 'three' >>> od.keys() - ["one", "two", "twohalf", "three", "four"] + ["one", "two", "two-point-five", "three", "four"] -Note that we also could have set the location of "twohalf" to be 'after two' -(i.e.: ``'>two'``). However, it's unlikely that you will have control over the +Note that we also could have set the location of "two-point-five" to be 'after two' +(i.e.: `'>two'`). However, it's unlikely that you will have control over the order in which extensions will be loaded, and this could affect the final -sorted order of an OrderedDict. For example, suppose an extension adding -'twohalf' in the above examples was loaded before a separate extension which -adds 'two'. You may need to take this into consideration when adding your +sorted order of an OrderedDict. For example, suppose an extension adding +"two-point-five" in the above examples was loaded before a separate extension +which adds 'two'. You may need to take this into consideration when adding your extension components to the various markdown OrderedDicts. Once an OrderedDict is created, the items are available via key: @@ -534,32 +536,32 @@ extension: md.reset() html2 = md.convert(text_without_footnote) -Without calling ``reset``, the footnote definitions from the first document will +Without calling `reset`, the footnote definitions from the first document will be inserted into the second document as they are still stored within the class -instance. Therefore the ``Extension`` class needs to define a ``reset`` method -that will reset the state of the extension (i.e.: ``self.footnotes = {}``). -However, as many extensions do not have a need for ``reset``, ``reset`` is only +instance. Therefore the `Extension` class needs to define a `reset` method +that will reset the state of the extension (i.e.: `self.footnotes = {}`). +However, as many extensions do not have a need for `reset`, `reset` is only called on extensions that are registered. -To register an extension, call ``md.registerExtension`` from within your -``extendMarkdown`` method: +To register an extension, call `md.registerExtension` from within your +`extendMarkdown` method: def extendMarkdown(self, md, md_globals): md.registerExtension(self) # insert processors and patterns here -Then, each time ``reset`` is called on the Markdown instance, the ``reset`` +Then, each time `reset` is called on the Markdown instance, the `reset` method of each registered extension will be called as well. You should also -note that ``reset`` will be called on each registered extension after it is +note that `reset` will be called on each registered extension after it is initialized the first time. Keep that in mind when over-riding the extension's -``reset`` method. +`reset` method. -### Config Settings {: #configsettings } +### Configuration Settings {: #configsettings } If an extension uses any parameters that the user may want to change, -those parameters should be stored in ``self.config`` of your -``markdown.extensions.Extension`` class in the following format: +those parameters should be stored in `self.config` of your +`markdown.extensions.Extension` class in the following format: class MyExtension(markdown.extensions.Extension): def __init__(self, **kwargs): @@ -567,7 +569,7 @@ those parameters should be stored in ``self.config`` of your 'option2' : ['value2', 'description2'] } super(MyExtension, self).__init__(**kwargs) -When implemented this way the config parameters can be over-ridden at +When implemented this way the configuration parameters can be over-ridden at run time (thus the call to `super`). For example: markdown.Markdown(extensions=[MyExtension(option1='other value']) @@ -576,38 +578,38 @@ Note that if a keyword is passed in that is not already defined in `self.config`, then a `KeyError` is raised. The `markdown.extensions.Extension` class and its subclasses have the -following methods available to assist in working with config settings: +following methods available to assist in working with configuration settings: -* **``getConfig(key [, default])``**: +* **`getConfig(key [, default])`**: Returns the stored value for the given `key` or `default` if the `key` does not exist. If not set, `default` returns an empty string. -* **``getConfigs()``**: +* **`getConfigs()`**: Returns a dict of all key/value pairs. -* **``getConfigInfo()``**: +* **`getConfigInfo()`**: - Returns all config descriptions as a list of tuples. + Returns all configuration descriptions as a list of tuples. -* **``setConfig(key, value)``**: +* **`setConfig(key, value)`**: - Sets a config setting for `key` with the given `value`. If `key` is + Sets a configuration setting for `key` with the given `value`. If `key` is unknown, a `KeyError` is raised. If the previous value of `key` was - a boolean value, then `value` is converted to a boolean value. If + a Boolean value, then `value` is converted to a Boolean value. If the previous value of `key` is `None`, then `value` is converted to - a boolean value except when it is `None`. No conversion takes place + a Boolean value except when it is `None`. No conversion takes place when the previous value of `key` is a string. -* **``setConfigs(items)``**: +* **`setConfigs(items)`**: - Sets multiple config settings given a dict of key/value pairs. + Sets multiple configuration settings given a dict of key/value pairs. -### makeExtension {: #makeextension } +### `makeExtension` {: #makeextension } As noted in the [library reference] an instance of an extension can be passed -directly to Markdown. In fact, this is the prefered way to use third-party +directly to Markdown. In fact, this is the preferred way to use third-party extensions. For example: @@ -617,7 +619,7 @@ For example: myext = myextension.MyExtension(option='value') md = markdown.Markdown(extensions=[myext]) -Markdown also accepts "named" third party extensions for those occassions +Markdown also accepts "named" third party extensions for those occasions when it is impractical to import an extension directly (from the command line or from within templates). @@ -627,7 +629,7 @@ to your users and would like to include a custom markdown extension within your library, that extension would be named `"mylib.mdext.myext"` where `mylib/mdext/myext.py` contains the extension and the `mylib` directory is on the PYTHONPATH. -The string can also include the name of the class seperated by a colon. +The string can also include the name of the class separated by a colon. Therefore, if you were to import the class like this: from path.to.module import SomeExtensionClass @@ -636,8 +638,8 @@ Then the named extension would comprise this string: "path.to.module:SomeExtensionClass" -You do not need to do anything special to support this feature. As long as your extension -class is able to be imported, a user can include it with the above syntax. +You do not need to do anything special to support this feature. As long as your +extension class is able to be imported, a user can include it with the above syntax. The above two methods are especially useful if you need to implement a large number of extensions with more than one residing in a module. However, if you do not want to require @@ -658,11 +660,11 @@ the module and call the `makeExtension` function to initiate your extension. [Preprocessors]: #preprocessors -[InlinePatterns]: #inlinepatterns +[Inline Patterns]: #inlinepatterns [Treeprocessors]: #treeprocessors [Postprocessors]: #postprocessors [BlockParser]: #blockparser -[Working with the ElementTree]: #working_with_et +[workingwithetree]: #working_with_et [Integrating your code into Markdown]: #integrating_into_markdown [extendMarkdown]: #extendmarkdown [OrderedDict]: #ordereddict diff --git a/docs/extensions/attr_list.txt b/docs/extensions/attr_list.txt index 01329c6..1951347 100644 --- a/docs/extensions/attr_list.txt +++ b/docs/extensions/attr_list.txt @@ -71,7 +71,7 @@ The above results in the following output: ### Inline ### To define attributes on inline elements, the attribute list should be defined -immediately after the inline element with no whitespace. +immediately after the inline element with no white space. [link](http://example.com){: class="foo bar" title="Some title!" } diff --git a/docs/extensions/code_hilite.txt b/docs/extensions/code_hilite.txt index 92f8c12..5e802b8 100644 --- a/docs/extensions/code_hilite.txt +++ b/docs/extensions/code_hilite.txt @@ -25,23 +25,23 @@ You will also need to [download][dl] and install the Pygments package on your appropriate rules for them, which are either defined in or linked from the header of your HTML templates. See the excellent [documentation][] for more details. If no language is defined, Pygments will attempt to guess the -language. When that fails, the code block will display as un-highlighted code. +language. When that fails, the code block will not be highlighted. [dl]: http://pygments.org/download/ [documentation]: http://pygments.org/docs !!! Note - The css and/or JavaScript is not included as part of this extension + The CSS and/or JavaScript is not included as part of this extension but must be provided by the end user. The Pygments project provides - default css styles which you may find to be a useful starting point. + default CSS styles which you may find to be a useful starting point. Syntax ------ The CodeHilite extension follows the same [syntax][] as regular Markdown code -blocks, with one exception. The hiliter needs to know what language to use for -the code block. There are three ways to tell the hiliter what language the code -block contains and each one has a different result. +blocks, with one exception. The highlighter needs to know what language to use for +the code block. There are three ways to tell the highlighter what language the +code block contains and each one has a different result. !!! Note The format of the language identifier only effects the display of line numbers @@ -52,9 +52,9 @@ block contains and each one has a different result. [syntax]: http://daringfireball.net/projects/markdown/syntax#precode -### SheBang (with path) ### +### Shebang (with path) ### -If the first line of the codeblock contains a shebang, the language is derived +If the first line of the code block contains a shebang, the language is derived from that and line numbers are used. #!/usr/bin/python @@ -65,7 +65,7 @@ Will result in: #!/usr/bin/python # Code goes here ... -### SheBang (no path) ### +### Shebang (no path) ### If the first line contains a shebang, but the shebang line does not contain a path (a single `/` or even a space), then that line is removed from the code @@ -92,7 +92,7 @@ Will result in: # Code goes here ... Certain lines can be selected for emphasis with the colon syntax. When -using Pygments' default css styles, emphasized lines have a yellow background. +using Pygments' default CSS styles, emphasized lines have a yellow background. This is useful to direct the reader's attention to specific lines. :::python hl_lines="1 3" @@ -143,7 +143,7 @@ The following options are provided to configure the output: Using `True` will force every code block to have line numbers, even when using colons (`:::`) for language identification. - Using `False` will turn off all line numbers, even when using SheBangs + Using `False` will turn off all line numbers, even when using shebangs (`#!`) for language identification. * **`guess_lang`**: @@ -157,7 +157,7 @@ The following options are provided to configure the output: `codehilite`. * **`pygments_style`**: - Pygments HTML Formatter Style (ColorScheme). Defaults to `default`. + Pygments HTML Formatter Style (`ColorScheme`). Defaults to `default`. !!! Note This is useful only when `noclasses` is set to `True`, otherwise the diff --git a/docs/extensions/extra.txt b/docs/extensions/extra.txt index bf4d12f..5347d81 100644 --- a/docs/extensions/extra.txt +++ b/docs/extensions/extra.txt @@ -1,7 +1,7 @@ title: Extra Extension prev_title: Extensions prev_url: index.html -next_title: Abreviations Extension +next_title: Abbreviations Extension next_url: abbreviations.html Python-Markdown Extra @@ -45,11 +45,19 @@ your own clone of Extra under a different name Markdown Inside HTML Blocks --------------------------- -Unlike the other Extra features, this feature is built into the markdown core and is turned on when `markdown.extensions.extra` is enabled. +Unlike the other Extra features, this feature is built into the markdown core and +is turned on when `markdown.extensions.extra` is enabled. -The content of any raw html block element can be Markdown-formatted simply by adding a `markdown` attribute to the opening tag. The markdown attribute will be stripped from the output, but all other attributes will be preserved. +The content of any raw HTML block element can be Markdown-formatted simply by +adding a `markdown` attribute to the opening tag. The markdown attribute will be +stripped from the output, but all other attributes will be preserved. -If the markdown value is set to `1` (recommended) or any value other than `span` or `block`, the default behavior will be executed: `p`,`h[1-6]`,`li`,`dd`,`dt`,`td`,`th`,`legend`, and `address` elements skip block parsing while others do not. If the default is overrident by a value of `span`, *block parsing will be skipped* regardless of tag. If the default is overriden by a value of `block`, *block parsing will occur* regardless of tag. +If the markdown value is set to `1` (recommended) or any value other than `span` +or `block`, the default behavior will be executed: `p`,`h[1-6]`,`li`,`dd`,`dt`, +`td`,`th`,`legend`, and `address` elements skip block parsing while others do not. +If the default is overridden by a value of `span`, *block parsing will be skipped* +regardless of tag. If the default is overridden by a value of `block`, +*block parsing will occur* regardless of tag. #### Simple Example: ``` @@ -67,8 +75,9 @@ This is *true* markdown text. </div> ``` -### Nested Markdown Inside HTML BLocks -Nested elements are more sensitive and must be used cautiously. To avoid unexpected results: +### Nested Markdown Inside HTML Blocks +Nested elements are more sensitive and must be used cautiously. To avoid +unexpected results: * Only nest elements within block mode elements. * Follow the closing tag of inner elements with a blank line. @@ -104,12 +113,12 @@ This `p` block *is* foolishly wrapped in further paragraph tags. The tail of the `BlockModeOverride` subelement. <div name="RawHtml"> -Raw html blocks may also be nested. +Raw HTML blocks may also be nested. </div> </div> -This text is after the markdown in html. +This text is after the markdown in HTML. ``` #### Result: ``` @@ -130,9 +139,9 @@ Note: Subelements are not required to have tail text.</div> </p> <p>The tail of the <code>BlockModeOverride</code> subelement.</p> <div name="RawHtml"> -Raw html blocks may also be nested. +Raw HTML blocks may also be nested. </div> </div> -<p>This text is after the markdown in html.</p> +<p>This text is after the markdown in HTML.</p> ``` diff --git a/docs/extensions/fenced_code_blocks.txt b/docs/extensions/fenced_code_blocks.txt index 19999fd..982f5d4 100644 --- a/docs/extensions/fenced_code_blocks.txt +++ b/docs/extensions/fenced_code_blocks.txt @@ -45,7 +45,7 @@ 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 +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: @@ -65,13 +65,13 @@ The above will output: <pre><code class="html"><p>HTML Document</p> </code></pre> -[Github][]'s backtick (`\``) syntax is also supported: +[GitHub][]'s backtick (`\``) syntax is also supported: ```python # more python code ``` -[Github]: http://github.github.com/github-flavored-markdown/ +[GitHub]: http://github.github.com/github-flavored-markdown/ ### Emphasized Lines ### diff --git a/docs/extensions/footnotes.txt b/docs/extensions/footnotes.txt index 40081e5..e9b0451 100644 --- a/docs/extensions/footnotes.txt +++ b/docs/extensions/footnotes.txt @@ -38,7 +38,7 @@ caret has any special meaning. A footnote content must start with the label followed by a colon and at least one space. The label used to define the content must exactly match the label used -in the body (including capitalization and whitespace). The content would then +in the body (including capitalization and white space). The content would then follow the label either on the same line or on the next line. The content may contain multiple lines, paragraphs, code blocks, blockquotes and most any other markdown syntax. The additional lines must be indented one level (four spaces or diff --git a/docs/extensions/header_id.txt b/docs/extensions/header_id.txt index 42e640e..5557b1b 100644 --- a/docs/extensions/header_id.txt +++ b/docs/extensions/header_id.txt @@ -55,14 +55,14 @@ The following options are provided to configure the output: Default: `1` The `level` setting allows you to automatically adjust the header levels to - fit within the hierarchy of your html templates. For example, suppose the + fit within the hierarchy of your HTML templates. For example, suppose the markdown text for a page should not contain any headers higher than level 3 (`<h3>`). The following will accomplish that: >>> text = ''' ... #Some Header ... ## Next Level''' - >>> from markdown.extensions.headerid import HeaderIdExtension + >>> from markdown.extensions.headerid import HeaderIdExtension >>> html = markdown.markdown(text, extensions=[HeaderIdExtension(level=3)]) >>> print html <h3 id="some_header">Some Header</h3> @@ -79,13 +79,14 @@ The following options are provided to configure the output: >>> text = ''' ... # Some Header ... # Header with ID # { #foo }''' - >>> html = markdown.markdown(text, - extensions=['attr_list', HeaderIdExtension(forceid=False)]) + >>> html = markdown.markdown(text, + extensions=['markdown.extensions.attr_list', + HeaderIdExtension(forceid=False)]) >>> print html <h1>Some Header</h1> <h1 id="foo">Header with ID</h1> -* **`separator`**: Word separator. Character which replaces whitespace in id. +* **`separator`**: Word separator. Character which replaces white space in id. Default: `-` diff --git a/docs/extensions/meta_data.txt b/docs/extensions/meta_data.txt index 517d3e6..3057bfa 100644 --- a/docs/extensions/meta_data.txt +++ b/docs/extensions/meta_data.txt @@ -49,7 +49,7 @@ line of a document must not be blank. Alternatively, if the first line in the document is `---`, a YAML document separator, then the meta-data is searched for between it and the next `---` -(or `...`) line. Even though YAML delimitors are supported, meta-data is +(or `...`) line. Even though YAML deliminators are supported, meta-data is not parsed as YAML unless the `yaml` option is set (see below). All meta-data is stripped from the document prior to any further processing @@ -69,7 +69,7 @@ The following options are provided to configure the output: If `yaml` is set to `True`, the lines between `---` separators are parsed as a full YAML object. PyYAML is required for this, and a warning is - issued if PyYAML (or equivalent) isn't available. + issued if PyYAML (or equivalent) is not available. Accessing the Meta-Data ----------------------- @@ -102,7 +102,7 @@ assumptions are made regarding the data. It is simply passed as found to the Note, if `yaml` option is set, the resulting `Meta` attribute is the object as returned by `yaml.load()` and may deviate significantly from the above -description (e.g. may be a list of dicts, with value objects other than +description (e.g. may be a list of dictionaries, with value objects other than strings, ...). Perhaps the meta-data could be passed into a template system, or used by diff --git a/docs/extensions/nl2br.txt b/docs/extensions/nl2br.txt index 1196615..8ba27c8 100644 --- a/docs/extensions/nl2br.txt +++ b/docs/extensions/nl2br.txt @@ -4,13 +4,13 @@ prev_url: meta_data.html next_title: Sane Lists Extension next_url: sane_lists.html -NL2BR -===== +New-Line-to-Break Extension +=========================== Summary ------- -The NL2BR extension will cause newlines to be treated as hard breaks; like +The New-Line-to-Break (`nl2b`) Extension will cause newlines to be treated as hard breaks; like StackOverflow and [GitHub][] flavored Markdown do. [Github]: http://github.github.com/github-flavored-markdown/ diff --git a/docs/extensions/smarty.txt b/docs/extensions/smarty.txt index a0680af..d511da1 100644 --- a/docs/extensions/smarty.txt +++ b/docs/extensions/smarty.txt @@ -26,7 +26,7 @@ Using the configuration option 'substitutions' you can overwrite the default substitutions. Just pass a dict mapping (a subset of) the keys to the substitution strings. -For example, one might use the following config to get correct quotes for +For example, one might use the following configuration to get correct quotes for the German language: extensionConfigs = { @@ -41,8 +41,8 @@ the German language: } !!! note - This extension reimplements the Python [SmartyPants] - library by intregated it into the markdown parser. + This extension re-implements the Python [SmartyPants] + library by integrating it into the markdown parser. While this does not provide any additional features, it does offer a few advantages. Notably, it will not try to work on highlighted code blocks (using the diff --git a/docs/extensions/toc.txt b/docs/extensions/toc.txt index 0705564..2cd1fa1 100644 --- a/docs/extensions/toc.txt +++ b/docs/extensions/toc.txt @@ -88,7 +88,7 @@ The following options are provided to configure the output: * **`permalink`**: Set to `True` or a string to generate permanent links at the end of each header. - Useful with Sphinx stylesheets. + Useful with Sphinx style sheets. When set to `True` the paragraph symbol (¶ or "`¶`") is used as the link text. When set to a string, the provided string is used as the link text. @@ -97,7 +97,7 @@ The following options are provided to configure the output: Base level for headers. Defaults to `1`. The `baselevel` setting allows the header levels to be automatically adjusted to - fit within the hierarchy of your html templates. For example, suppose the + fit within the hierarchy of your HTML templates. For example, suppose the Markdown text for a page should not contain any headers higher than level 3 (`<h3>`). The following will accomplish that: @@ -124,4 +124,4 @@ The following options are provided to configure the output: The callable must return a string appropriate for use in HTML `id` attributes. * **`separator`**: - Word separator. Character which replaces whitespace in id. Defaults to "`-`".
\ No newline at end of file + Word separator. Character which replaces white space in id. Defaults to "`-`".
\ No newline at end of file diff --git a/docs/extensions/wikilinks.txt b/docs/extensions/wikilinks.txt index b52e0d0..948b957 100644 --- a/docs/extensions/wikilinks.txt +++ b/docs/extensions/wikilinks.txt @@ -25,12 +25,12 @@ number, dashes, underscores and spaces surrounded by double brackets. Therefore [[Bracketed]] -would produce the following html: +would produce the following HTML: <a href="/Bracketed/" class="wikilink">Bracketed</a> -Note that wikilinks are automatically assigned `class="wikilink"` making it -easy to style wikilinks differently from other links on a page if one so +Note that WikiLinks are automatically assigned `class="wikilink"` making it +easy to style WikiLinks differently from other links on a page if one so desires. See below for ways to alter the class. Also note that when a space is used, the space is converted to an underscore in @@ -54,7 +54,7 @@ configuring extensions. The default behavior is to point each link to the document root of the current domain and close with a trailing slash. Additionally, each link is assigned to -the html class `wikilink`. +the HTML class `wikilink`. The following options are provided to change the default behavior: @@ -74,7 +74,7 @@ The following options are provided to change the default behavior: ### Examples ### -For an example, let us suppose links should always point to the subdirectory +For an example, let us suppose links should always point to the sub-directory `/wiki/` and end with `.html` >>> from markdown.extensions.wikilinks import WikiLinkExtension @@ -104,7 +104,7 @@ The option is also provided to change or remove the class attribute. ... extensions=[WikiLinkExtension(html_class='myclass')] ... ) -Would cause all wikilinks to be assigned to the class `myclass`. +Would cause all WikiLinks to be assigned to the class `myclass`. <a href="/WikiLink/" class="myclass">WikiLink</a> diff --git a/docs/install.txt b/docs/install.txt index d24e1ba..1989398 100644 --- a/docs/install.txt +++ b/docs/install.txt @@ -24,7 +24,7 @@ That's it! You're ready to [use](reference.html) Python-Markdown. Enjoy! Installing on Windows {: #windows } ----------------------------------- -Download the Windows installer (.exe) from +Download the Windows installer (`.exe`) from [PyPI](http://pypi.python.org/pypi/Markdown) Double-click the file and follow the instructions. @@ -58,7 +58,7 @@ Using the Git Repository {: #git } If you're the type that likes to live on the edge, you may want to keep up with the latest additions and bug fixes in the repository between releases. -Python-Markdown is maintained in a Git repository on github.com. To +Python-Markdown is maintained in a Git repository on GitHub.com. To get a copy of Python-Markdown from the repository do the following from the command line: diff --git a/docs/reference.txt b/docs/reference.txt index 2e1985d..ac5c724 100644 --- a/docs/reference.txt +++ b/docs/reference.txt @@ -35,7 +35,7 @@ method appropriately ([see below](#convert)). The following options are available on the `markdown.markdown` function: -* __`text`__{: #text } (required): The source unicode string. +* __`text`__{: #text } (required): The source Unicode string. !!! note "Important" Python-Markdown expects **Unicode** as input (although @@ -69,14 +69,14 @@ The following options are available on the `markdown.markdown` function: extensions=[MyExtension(), 'path.to.my.ext'] !!! note - The prefered method is to pass in an instance of an extension. Strings - should only be used when it is impossable to import the Extension Class + The preferred method is to pass in an instance of an extension. Strings + should only be used when it is impossible to import the Extension Class directly (from the command line or in a template). When passing in extension instances, each class instance must be a subclass of `markdown.extensions.Extension` and any configuration options should be defined when initiating the class instance rather than using the - [extension_configs](#extension_configs) keyword. For example: + [`extension_configs`](#extension_configs) keyword. For example: from markdown.extensions import Extension class MyExtension(Extension): @@ -89,8 +89,8 @@ The following options are available on the `markdown.markdown` function: supported. Therefore, to import the 'extra' extension, one could do `extensions=['markdown.extensions.extra']` - Additionaly, a Class may be specified in the name. The class must be at the end of - the name and be seperated by a colon from the module. + Additionally, a Class may be specified in the name. The class must be at the end of + the name and be separated by a colon from the module. Therefore, if you were to import the class like this: @@ -108,7 +108,7 @@ The following options are available on the `markdown.markdown` function: When loading an extension by name (as a string), you may pass in configuration settings to the extension using the - [extension_configs](#extension_configs) keyword. + [`extension_configs`](#extension_configs) keyword. !!! seealso "See Also" See the documentation of the [Extension API](extensions/api.html) for @@ -122,7 +122,7 @@ The following options are available on the `markdown.markdown` function: configuration settings directly to the class when initializing it. !!! Note - The prefered method is to pass in an instance of an extension, which + The preferred method is to pass in an instance of an extension, which does not require use of the `extension_configs` keyword at all. See the [extensions](#extensions) keyword for details. @@ -159,14 +159,14 @@ The following options are available on the `markdown.markdown` function: The values can be in either lowercase or uppercase. !!! warning - It is suggested that the more specific formats ("xhtml1", "html5", & - "html4") be used as the more general formats ("xhtml" or "html") may + It is suggested that the more specific formats (`"xhtml1"`, `"html5"`, & + `"html4"`) be used as the more general formats (`"xhtml"` or `"html"`) may change in the future if it makes sense at that time. -* __`safe_mode`__{: #safe_mode }: Disallow raw html. +* __`safe_mode`__{: #safe_mode }: Disallow raw HTML. !!! warning - "`safe_mode`" is pending deprecation and should not be used. + "`safe_mode`" is deprecated and should not be used. HTML sanitizers (like [Bleach]) provide a better solution for dealing with markdown text submitted by untrusted users. @@ -178,7 +178,7 @@ The following options are available on the `markdown.markdown` function: See the [release notes] for more info. [Bleach]: https://github.com/jsocol/bleach -[release notes]: release-2.5.html +[release notes]: release-2.6.html The following values are accepted: @@ -215,7 +215,7 @@ The following options are available on the `markdown.markdown` function: safe_mode is set to `replace`. Defaults to `[HTML_REMOVED]`. !!! warning - "`html_replacement_text`" is pending deprecation and should not be used. + "`html_replacement_text`" is deprecated and should not be used. See the [release notes] for more info. * __`tab_length`__{: #tab_length }: Length of tabs in the source. Default: 4 @@ -277,11 +277,11 @@ Instead, it accepts the following required options: * or `None` (default) which will write to `stdout`. * __`encoding`__{: #encoding }: The encoding of the source text file. Defaults - to "utf-8". The same encoding will always be used for input and output. - The 'xmlcharrefreplace' error handler is used when encoding the output. + to `"utf-8"`. The same encoding will always be used for input and output. + The `xmlcharrefreplace` error handler is used when encoding the output. !!! Note - This is the only place that decoding and encoding of unicode + This is the only place that decoding and encoding of Unicode takes place in Python-Markdown. If this rather naive solution does not meet your specific needs, it is suggested that you write your own code to handle your encoding/decoding needs. diff --git a/docs/release-2.0.1.txt b/docs/release-2.0.1.txt index c40b471..c0b890a 100644 --- a/docs/release-2.0.1.txt +++ b/docs/release-2.0.1.txt @@ -16,7 +16,7 @@ Backwards-incompatible Changes ------------------------------ Due to various complications in how Python handles command line scripts in -differance systems and with differant installation tools, we were forced to -rename the commandline script to ``markdown`` (no ".py"). A matching batch +difference systems and with different installation tools, we were forced to +rename the command line script to `markdown` (no `.py`). A matching batch script will get installed on Windows. Any shell scripts which call -``markdown.py`` will need to be altered to call ``markdown`` instead. +`markdown.py` will need to be altered to call `markdown` instead. diff --git a/docs/release-2.0.txt b/docs/release-2.0.txt index ec11522..f44b0c5 100644 --- a/docs/release-2.0.txt +++ b/docs/release-2.0.txt @@ -14,7 +14,7 @@ extensions to the distribution (including an extension that mimics PHP Markdown Extra), all while maintaining backward compatibility with the end user API in version 1.7. -Python-Markdown supports Python versions 2.3, 2.4, 2.5, and 2.6. We've even +Python-Markdown supports Python versions 2.3, 2.4, 2.5, and 2.6. We have even released a version converted to Python 3.0! Backwards-incompatible Changes diff --git a/docs/release-2.1.0.txt b/docs/release-2.1.0.txt index 606bad2..efb3b4a 100644 --- a/docs/release-2.1.0.txt +++ b/docs/release-2.1.0.txt @@ -11,10 +11,10 @@ We are pleased to release Python-Markdown 2.1 which makes many improvements on 2.0. In fact, we consider 2.1 to be what 2.0 should have been. While 2.1 consists mostly of bug fixes, bringing Python-Markdown more inline with other implementations, some internal improvements were made to the parser, -a few new builtin extensions were added, and HTML5 support was added. +a few new built-in extensions were added, and HTML5 support was added. Python-Markdown supports Python versions 2.4, 2.5, 2.6, 2.7, 3.1, and 3.2 out -of the box. In fact, the same codebase installs on Python 3.1 and 3.2 with no +of the box. In fact, the same code base installs on Python 3.1 and 3.2 with no extra work by the end user. Backwards-incompatible Changes @@ -46,7 +46,7 @@ variables (either by editing the source or by overriding them in your code), you should now set them on the class. See the [Library Reference](reference.html) for the options available. -* If you have been using the [HeaderID](extensions/header_id.html) extension +* If you have been using the [HeaderId](extensions/header_id.html) extension to define custom ids on headers, you will want to switch to using the new [Attribute List](extensions/attr_list.html) extension. The HeaderId extension now only auto-generates ids on headers which have not already had ids defined. @@ -57,9 +57,9 @@ Attribute Lists instead of HeaderId as it did previously. in the `markdown` namespace. Extension authors may need to adjust a few import statements in their extensions to work with the changes. -* The commandline script name was changed to `markdown_py`. The previous name +* The command line script name was changed to `markdown_py`. The previous name (`markdown`) was conflicting with people (and Linux package systems) who also -had markdown.pl installed on there system as markdown.pl's commandline script +had markdown.pl installed on there system as markdown.pl's command line script was also named `markdown`. Be aware that installing Python-Markdown 2.1 will not remove the old versions of the script with different names. You may want to remove them yourself as they are unlikely to work properly. @@ -69,18 +69,18 @@ What's New in Python-Markdown 2.1 Three new extensions were added. [Attribute Lists](extensions/attr_list.html), which was inspired by Maruku's feature of the same name, -[Newline to Break](extensions/nl2br.html), which was inspired by Github +[Newline to Break](extensions/nl2br.html), which was inspired by GitHub Flavored Markdown, and [Smart Strong](extensions/smart_strong.html), which fills a hole in the Extra extension. HTML5 is now supported. All this really means is that new block level elements introduced in the HTML5 spec are now properly recognized as raw HTML. As valid HTML5 can consist of either HTML4 or XHTML1, there is no need to add a -new HTML5 searializers. That said, `html5` and `xhtml5` have been added as -aliases of the `html4` and `xhtml1` searializers respectively. +new HTML5 serializers. That said, `html5` and `xhtml5` have been added as +aliases of the `html4` and `xhtml1` serializers respectively. -An XHTML searializer has been added. Previously, ElementTree's XML searializer -was being used for XHTML output. With the new searliazer we are able to avoid +An XHTML serializer has been added. Previously, ElementTree's XML serializer +was being used for XHTML output. With the new serializer we are able to avoid more invalid output like empty elements (i.e., `<p />`) which can choke browsers. @@ -100,7 +100,7 @@ build a parser of a different markup language without the overhead of building the markdown parser and throwing it away. Import statements within markdown have been improved so that third party -libraries can embed the markdown library if they desire (licencing permitting). +libraries can embed the markdown library if they desire (licensing permitting). Added support for Python's `-m` command line option. You can run the markdown package as a command line script. Do `python -m markdown [options] [args]`. @@ -108,13 +108,13 @@ Note that this is only fully supported in Python 2.7+. Python 2.5 & 2.6 require you to call the module directly (`markdown.__main__`) rather than the package (`markdown`). This does not work in Python 2.4. -The commandline script has been renamed to `markdown_py` which avoids all the -various problems we had with previous names. Also improved the commandline -script to accept input on stdin. +The command line script has been renamed to `markdown_py` which avoids all the +various problems we had with previous names. Also improved the command line +script to accept input on `stdin`. The testing framework has been completely rebuilt using the Nose testing framework. This provides a number of benefits including the ability to better -test the builtin extensions and other options available to change the parsing +test the built-in extensions and other options available to change the parsing behavior. See the [Test Suite](test_suite.html) documentation for details. Various bug fixes have been made, which are too numerous to list here. See the diff --git a/docs/release-2.2.0.txt b/docs/release-2.2.0.txt index 59ac78f..c3750fa 100644 --- a/docs/release-2.2.0.txt +++ b/docs/release-2.2.0.txt @@ -45,7 +45,7 @@ What's New in Python-Markdown 2.1 The docs were refactored and can now be found at
<http://packages.python.org/Markdown/>. The docs are now maintained in the
-Repo and are generated by the `setup.py build_docs` command.
+Repository and are generated by the `setup.py build_docs` command.
The [Sane_Lists](http://packages.python.org/Markdown/extensions/sane_lists.html)
extension was added. The Sane Lists Extension alters the behavior of the
@@ -60,7 +60,7 @@ As long as the provided module contains a compatible extension, the extension will be loaded.
The BlockParser API was slightly altered to allow `blockprocessor.run` to return
-`True` or `False` which provides more control to the block proccessor loop from
+`True` or `False` which provides more control to the block processor loop from
within any Blockprocessor instance.
Various bug fixes have been made. See the
diff --git a/docs/release-2.3.txt b/docs/release-2.3.txt index d2cef63..a15e584 100644 --- a/docs/release-2.3.txt +++ b/docs/release-2.3.txt @@ -26,37 +26,37 @@ longer try to import a third-party installation of ElementTree. subclass from 'object'. While this is not likely to affect most users, extension authors may need to make a few minor adjustments to their code. -* "safe_mode" has been further restricted. Markdown formated links must be -of a known whitelisted scheme when in "safe_mode" or the url is discarded. -The whitelisted schemes are: 'http', 'https', 'ftp', 'ftps', 'mailto', and -'news'. Schemeless urls are also permitted, but are checked in other ways - +* "safe_mode" has been further restricted. Markdown formatted links must be +of a known white-listed scheme when in "safe_mode" or the URL is discarded. +The white-listed schemes are: 'HTTP', 'HTTPS', 'FTP', 'FTPS', 'MAILTO', and +'news'. Schemeless URLs are also permitted, but are checked in other ways - as they have been for some time. * The ids assigned to footnotes now contain a dash (`-`) rather than a colon -(`:`) when `output_format` it set to "html5" or "xhtml5". If you are making +(`:`) when `output_format` it set to `"html5"` or `"xhtml5"`. If you are making reference to those ids in your JavaScript or CSS and using the HTML5 output, you will need to update your code accordingly. No changes are necessary if -you are outputing XHTML (the default) or HTML4. +you are outputting XHTML (the default) or HTML4. -* The "force_linenos" config setting of the CodeHilite extension has been -marked as **Pending Deprecation** and a new setting "linenums" has been added to +* The `force_linenos` configuration setting of the CodeHilite extension has been +marked as **Pending Deprecation** and a new setting `linenums` has been added to replace it. See documentation for the [CodeHilite Extension] for an explanation -of the new "linenums" setting. The new setting will honor the old -"force_linenos" if it is set, but it will raise a PendingDeprecationWarning +of the new `linenums` setting. The new setting will honor the old +`force_linenos` if it is set, but it will raise a `PendingDeprecationWarning` and will likely be removed in a future version of Python-Markdown. [CodeHilite Extension]: extensions/codehilite.html * The "RSS" extension has been removed and no longer ships with Python-Markdown. -If you would like to continue using the extension (not recomended), it is -archived on [Github](https://gist.github.com/waylan/4773365). +If you would like to continue using the extension (not recommended), it is +archived on [GitHub](https://gist.github.com/waylan/4773365). * The "HTML Tidy" Extension has been removed and no longer ships with Python-Markdown. -If you would like to continue using the extension (not recomended), it is -archived on [Github](https://gist.github.com/waylan/5152650). Note that the -underlying library, uTidylib, is not Python 3 compatable. Instead, it is +If you would like to continue using the extension (not recommended), it is +archived on [GitHub](https://gist.github.com/waylan/5152650). Note that the +underlying library, uTidylib, is not Python 3 compatible. Instead, it is recommended that the newer [PyTidyLib] (version 0.2.2+ for Python 3 -compatability - install from github not PyPI) be used. As the API for that +comparability - install from GitHub not PyPI) be used. As the API for that library is rather simple, it is recommended that the output of Markdown be wrapped in a call to PyTidyLib rather than using an extension (for example: `tidylib.tidy_fragment(markdown.markdown(source), options={...})`). @@ -68,10 +68,10 @@ What's New in Python-Markdown 2.3 * The entire code base now universally runs in Python 2 and Python 3 without any need for running the 2to3 conversion tool. This not only simplifies testing, -but by using unicode_literals, results in more consistent behavior across +but by using Unicode_literals, results in more consistent behavior across Python versions. Additionally, the relative imports (made possible in Python 2 via absolute_import) allows the entire library to more easily be embedded in a -subdirectory of another project. The various files within the library will +sub-directory of another project. The various files within the library will still import each other properly even though 'markdown' may not be in Python's root namespace. diff --git a/docs/release-2.4.txt b/docs/release-2.4.txt index af2110b..c32408c 100644 --- a/docs/release-2.4.txt +++ b/docs/release-2.4.txt @@ -15,12 +15,12 @@ Python-Markdown supports Python versions 2.6, 2.7, 3.1, 3.2, and 3.3. Backwards-incompatible Changes ------------------------------ -* The "force_linenos" config setting of the CodeHilite extension has been +* The `force_linenos` configuration setting of the CodeHilite extension has been marked as **Deprecated**. It had previously been marked as "Pending Deprecation" -in version 2.3 when a new setting "linenums" was added to replace it. See +in version 2.3 when a new setting `linenums` was added to replace it. See documentation for the [CodeHilite Extension] for an explanation of the new -"linenums" setting. The new setting will honor the old "force_linenos" if it -is set, but "force_linenos" will raise a DeprecationWarning and will likely +`linenums` setting. The new setting will honor the old `force_linenos` if it +is set, but `force_linenos` will raise a `DeprecationWarning` and will likely be removed in a future version of Python-Markdown. [CodeHilite Extension]: extensions/code_hilite.html @@ -34,7 +34,7 @@ What's New in Python-Markdown 2.4 * Thanks to the hard work of [Dmitry Shachnev] the [Smarty Extension] has been added, which implements [SmartyPants] using Python-Markdown's Extension API. -This offers a few benefits over a third party sript. The HTML does not need +This offers a few benefits over a third party script. The HTML does not need to be "tokenized" twice, no hacks are required to combine SmartyPants and code highlighting, and we get markdown's escaping feature for free. Please try it out and report bugs and/or improvements. diff --git a/docs/release-2.5.txt b/docs/release-2.5.txt index 5b3e5f7..0c399ed 100644 --- a/docs/release-2.5.txt +++ b/docs/release-2.5.txt @@ -20,7 +20,7 @@ Backwards-incompatible Changes [importlib]: https://pypi.python.org/pypi/importlib -* The `force_linenos` config key on the [CodeHilite Extension] has been **deprecated** +* The `force_linenos` configuration key on the [CodeHilite Extension] has been **deprecated** and will raise a `KeyError` if provided. In the previous release (2.4), it was issuing a `DeprecationWarning`. The [`linenums`][linenums] keyword should be used instead, which provides more control of the output. @@ -56,14 +56,14 @@ Backwards-incompatible Changes html = markdown.markdown(text, extensions=[EscapeHtml()]) - As the HTML would not be parsed with the above Extension, then the searializer will + As the HTML would not be parsed with the above Extension, then the serializer will escape the raw HTML, which is exactly what happens now when `safe_mode="escape"`. [Bleach]: http://bleach.readthedocs.org/ * Positional arguments on the `markdown.Markdown()` are pending deprecation as are all except the `text` argument on the `markdown.markdown()` wrapper function. - Only keyword arguments should be used. For example, if your code previosuly + Only keyword arguments should be used. For example, if your code previously looked like this: html = markdown.markdown(text, ['extra']) @@ -74,14 +74,14 @@ Backwards-incompatible Changes !!! Note This change is being made as a result of deprecating `"safe_mode"` as the - `safe_mode` argumnet was one of the positional arguments. When that argument + `safe_mode` argument was one of the positional arguments. When that argument is removed, the two arguments following it will no longer be at the correct - position. It is recomended that you always use keywords when they are supported + position. It is recommended that you always use keywords when they are supported for this reason. -* In previous versions of Python-Markdown, the builtin extensions received - special status and did not require the full path to be provided. Additionaly, - third party extensions whose name started with "mdx_" received the same +* In previous versions of Python-Markdown, the built-in extensions received + special status and did not require the full path to be provided. Additionally, + third party extensions whose name started with `"mdx_"` received the same special treatment. This behavior will be deprecated in version 2.6 and will raise a **`PendingDeprecationWarning`** in 2.5. Ensure that you always use the full path to your extensions. For example, if you previously did the following: @@ -96,21 +96,21 @@ Backwards-incompatible Changes $ python -m markdown -x markdown.extensions.extra input.txt - See the [documentation](reference.html#extensions) for a full explaination + See the [documentation](reference.html#extensions) for a full explanation of the current behavior. -* The previously documented method of appending the extension configs as +* The previously documented method of appending the extension configuration as a string to the extension name will be deprecated in Python-Markdown version 2.6 and will raise a **`PendingDeprecationWarning`** in 2.5. The - [extension_configs](reference.html#extension_configs) keyword should + [`extension_configs`](reference.html#extension_configs) keyword should be used instead. See the [documentation](reference.html#extension-configs) - for a full explaination of the current behavior. + for a full explanation of the current behavior. What's New in Python-Markdown 2.5 --------------------------------- * The [Smarty Extension] has had a number of additional configuration settings - added, which allows one to define their own subtitutions to better support + added, which allows one to define their own substitutions to better support languages other than English. Thanks to [Martin Altmayer] for implementing this feature. @@ -121,10 +121,10 @@ What's New in Python-Markdown 2.5 `markdown.Markdown`) can now point to any module and/or Class on your PYTHONPATH. While dot notation was previously supported, a module could not be at the root of your PYTHONPATH. The name had to contain at least one dot (requiring it to be a - submodule). This restriction no longer exists. + sub-module). This restriction no longer exists. - Additionaly, a Class may be specified in the name. The class must be at the end of - the name (which uses dot notation from PYTHONPATH) and be seperated by a colon from + Additionally, a Class may be specified in the name. The class must be at the end of + the name (which uses dot notation from PYTHONPATH) and be separated by a colon from the module. Therefore, if you were to import the class like this: @@ -136,37 +136,37 @@ What's New in Python-Markdown 2.5 "path.to.module:SomeExtensionClass" This allows multiple extensions to be implemented within the same module and still - accessable when the user isn't able to import the extension directly (perhaps from + accessible when the user is not able to import the extension directly (perhaps from a template filter or the command line). This also means that extension modules are no longer required to include the `makeExtension` function which returns an instance of the extension class. However, if the user does not specify the class name (she only provides `"path.to.module"`) the extension will fail to load without the `makeExtension` function included in - the module. Extension authors will want to document carfully what is required to + the module. Extension authors will want to document carefully what is required to load their extensions. [ex]: reference.html#extensions -* The Extension Configuration code has been refactord to make it a little easier - for extension authors to work with config settings. As a result, the +* The Extension Configuration code has been refactored to make it a little easier + for extension authors to work with configuration settings. As a result, the [`extension_configs`][ec] keyword now accepts a dictionary rather than requiring a list of tuples. A list of tuples is still supported so no one needs to change their existing code. This should also simplify the learning curve for new users. Extension authors are encouraged to review the new methods available on the - `markdown.extnesions.Extension` class for handling configs and adjust their + `markdown.extnesions.Extension` class for handling configuration and adjust their code going forward. The included extensions provide a model for best practices. - See the [API] documentation for a full explaination. + See the [API] documentation for a full explanation. [ec]: reference.html#extension_configs [API]: extensions/api.html#configsettings * The [Command Line Interface][cli] now accepts a `--extensions_config` (or `-c`) - option which accepts a filename and passes the parsed content of a [YAML] or + option which accepts a file name and passes the parsed content of a [YAML] or [JSON] file to the [`extension_configs`][ec] keyword of the `markdown.Markdown` class. The contents of the YAML or JSON must map to a Python Dictionary which - matches the format required by the `extension_configs` kerword. Note that + matches the format required by the `extension_configs` keyword. Note that [PyYAML] is required to parse YAML files. [cli]: cli.html#using-extensions diff --git a/docs/release-2.6.txt b/docs/release-2.6.txt index 030d890..0a95780 100644 --- a/docs/release-2.6.txt +++ b/docs/release-2.6.txt @@ -44,7 +44,7 @@ Backwards-incompatible Changes html = markdown.markdown(text, extensions=[EscapeHtml()]) - As the HTML would not be parsed with the above Extension, then the searializer will + As the HTML would not be parsed with the above Extension, then the serializer will escape the raw HTML, which is exactly what happens now when `safe_mode="escape"`. [Bleach]: http://bleach.readthedocs.org/ @@ -70,7 +70,7 @@ Backwards-incompatible Changes * In previous versions of Python-Markdown, the built-in extensions received special status and did not require the full path to be provided. Additionally, - third party extensions whose name started with "mdx_" received the same + third party extensions whose name started with `"mdx_"` received the same special treatment. This behavior is deprecated and will raise a **`DeprecationWarning`** in version 2.6 and an error in 2.7. Ensure that you always use the full path to your extensions. For example, if you previously @@ -89,10 +89,10 @@ Backwards-incompatible Changes See the [documentation](reference.html#extensions) for a full explanation of the current behavior. -* The previously documented method of appending the extension configs as +* The previously documented method of appending the extension configuration options as a string to the extension name is deprecated and will raise a **`DeprecationWarning`** in version 2.6 and an error in 2.7. - The [extension_configs](reference.html#extension_configs) keyword should + The [`extension_configs`](reference.html#extension_configs) keyword should be used instead. See the [documentation](reference.html#extension-configs) for a full explanation of the current behavior. @@ -110,7 +110,7 @@ Backwards-incompatible Changes [hid]: extensions/header_id.html * Positional arguments and the `configs` keyword on the `markdown.extension.Extension` class - (and its subclasses) are deprecated. Each individual config option should be passed + (and its subclasses) are deprecated. Each individual configuration option should be passed to the class as a keyword/value pair. For example. one might have previously initiated an extension subclass like this: @@ -131,13 +131,13 @@ Backwards-incompatible Changes def makeExtension(**kwargs): return SomeExtension(**kwargs) - Failing to do so will result in a DeprecationWarning and will raise an error in the next + Failing to do so will result in a **`DeprecationWarning`** and will raise an error in the next release. See the [Extension API][mext] documentation for more information. In the event that an `markdown.extension.Extension` subclass overrides the `__init__` method - and implements its own config handling, then the above may not apply. However, it is - recommended that the subclass still calls the parent `__init__` method to handle configs - like so: + and implements its own configuration handling, then the above may not apply. However, it is + recommended that the subclass still calls the parent `__init__` method to handle configuration + options like so: class SomeExtension(markdown.extension.Extension): def __init__(**kwargs): @@ -151,7 +151,7 @@ Backwards-incompatible Changes super(MyExtension, self).__init__(**kwargs) # Do post-config stuff here - Note the call to `super` to get the benefits of config handling from the parent class. + Note the call to `super` to get the benefits of configuration handling from the parent class. See the [documentation][config] for more information. [config]: extensions/api.html#configsettings @@ -176,39 +176,39 @@ worked on PyPy for some time, it is now officially supported and tested on PyPy. [Meta-Data]: extensions/meta_data.html [YAML]: http://yaml.org/ -* The [Table fo Contents][TOC] Extension has been refactored and some new features +* The [Table of Contents][TOC] Extension has been refactored and some new features have been added. See the documentation for a full explanation of each feature listed below: * The extension now assigns the Table of Contents to the `toc` attribute of the Markdown class regardless of whether a "marker" was found in the document. Third party frameworks no longer need to insert a "marker," run the document - through Markdown, then extract the TOC from the document. + through Markdown, then extract the Table of Contents from the document. - * The TOC Extension is now a "registered extension." Therefore, when the `reset` + * The Table of Contents Extension is now a "registered extension." Therefore, when the `reset` method of the Markdown class is called, the `toc` attribute on the Markdown class is cleared (set to an empty string). - * When the `marker` config option is set to an empty string, the parser completely + * When the `marker` configuration option is set to an empty string, the parser completely skips the process of searching the document for markers. This should save parsing - time when the TOC Extension is being used only to assign ids to headers. + time when the Table of Contents Extension is being used only to assign ids to headers. - * A `separator` config option has been added allowing users to override the + * A `separator` configuration option has been added allowing users to override the separator character used by the slugify function. - * A `baselevel` config option has been added allowing users to set the base level + * A `baselevel` configuration option has been added allowing users to set the base level of headers in their documents (h1-h6). This allows the header levels to be automatically adjusted to fit within the hierarchy of an HTML template. [TOC]: extensions/toc.html -* The [CodeHilite][ch] Extension has gained a new config option: `use_pygments`. +* The [CodeHilite][ch] Extension has gained a new configuration option: `use_pygments`. The option is `True` by default, however, it allows one to turn off Pygments code highlighting (set to `False`) while preserving the language detection features of - the extension. Note that Pygments language detection is not used as that would 'use - Pygments`. If a language is defined for a code block, it will be assigned to the + the extension. Note that Pygments language guessing is not used as that would 'use + Pygments'. If a language is defined for a code block, it will be assigned to the `<code>` tag as a class in the manner suggested by the [HTML5 spec][spec] - (alternate output will not be entertained) and might be used by a JavaScript + (alternate output will not be entertained) and could potentially be used by a JavaScript library in the browser to highlight the code block. [ch]: extensions/code_hilite.html diff --git a/docs/siteindex.txt b/docs/siteindex.txt index 19072d8..0139bd7 100644 --- a/docs/siteindex.txt +++ b/docs/siteindex.txt @@ -21,9 +21,9 @@ Table of Contents * [Library Reference](reference.html) * [The Basics](reference.html#the-basics) * [The Details](reference.html#the-details) - * [markdown.markdown](reference.html#markdown) - * [markdown.markdownFromFile](reference.html#markdownFromFile) - * [markdown.Markdown](reference.html#Markdown) + * [`markdown.markdown`](reference.html#markdown) + * [`markdown.markdownFromFile`](reference.html#markdownFromFile) + * [`markdown.Markdown`](reference.html#Markdown) * [Command Line](cli.html) * [Setup](cli.html#setup) * [Usage](cli.html#usage) @@ -50,7 +50,7 @@ Table of Contents * [Third Party Extensions](extensions/index.html#third-party-extensions) * [Extension API](extensions/api.html) * [Preprocessors](extensions/api.html#preprocessors) - * [InlinePatterns](extensions/api.html#inlinepatterns) + * [Inline Patterns](extensions/api.html#inlinepatterns) * [Treeprocessors](extensions/api.html#treeprocessors) * [Postprocessors](extensions/api.html#postprocessors) * [BlockParser](extensions/api.html#blockparser) @@ -59,11 +59,11 @@ Table of Contents * [extendMarkdown](extensions/api.html#extendmarkdown) * [OrderedDict](extensions/api.html#ordereddict) * [registerExtension](extensions/api.html#registerextension) - * [Config Settings](extensions/api.html#configsettings) + * [Configuration Settings](extensions/api.html#configsettings) * [makeExtension](extensions/api.html#makeextension) * [Test Suite](test_suite.html) * [Markdown Syntax Test](test_suite.html#markdown-syntax-tests) - * [Syntax Test Config Settings](test_suite.html#syntax-test-config-settings) + * [Syntax Test Configuration Settings](test_suite.html#syntax-test-config-settings) * [Unit Tests](test_suite.html#unit-tests) * [Change Log](change_log.html) * [Release Notes for v.2.6](release-2.6.html) diff --git a/docs/test_suite.txt b/docs/test_suite.txt index 43829e9..745ed3b 100644 --- a/docs/test_suite.txt +++ b/docs/test_suite.txt @@ -16,14 +16,14 @@ Fortin's [PHP] implementation. The test suite can be run by calling the `run_tests.py` command at the root of the distribution tarball or by calling the `nosetests` command directly. Either way, Nose will need to be installed on your system first (run `easy_install -nose`). Any standard nosetests config options can be passed in on the command +nose`). Any standard nosetests configuration options can be passed in on the command line (i.e.: verbosity level or use of a plugin like coverage). Additionally, a nicely formatted HTML report of all output is written to a temporary file in `test-output.html`. Open the file in a browser to view the report. -A tox.ini file is also provided, so [tox] can be used to automatically create +A `tox.ini` file is also provided, so [tox] can be used to automatically create virtual environments, install all testing dependencies and run the tests on each supported Python version. See the wiki for instructions on [setting up a testing environment] to use tox. @@ -34,11 +34,11 @@ Tests. ## Markdown Syntax Tests The Syntax Tests are in the various directories contained within the 'tests' -directory of the packaged tarball. Each test consists of a matching pair of txt -and html files. The txt file contains a snippet of Markdown source text -formated for a specific syntax feature and the html file contains the expected -HTML output of that snippet. When the test suite is run, each txt file is run -through Markdown and the output is compared with the html file as a separate +directory of the packaged tarball. Each test consists of a matching pair of text +and HTML files. The text file contains a snippet of Markdown source text +formatted for a specific syntax feature and the HTML file contains the expected +HTML output of that snippet. When the test suite is run, each text file is run +through Markdown and the output is compared with the HTML file as a separate Unit Test. In fact, this is the primary reason for using Nose, it gives us an easy way to @@ -80,7 +80,7 @@ insignificant white space differences: Note that 219 tests were run, one of which failed with a `MarkdownSyntaxError`. Only Markdown Syntax Tests should fail with a `MarkdownSyntaxError`. Nose then formats the error reports for `MarkdownSyntaxError`s so that they only include -useful information. Namely the txt file which failed and a unified diff showing +useful information. Namely the text file which failed and a unified diff showing the failure. Without the plugin, you would also get a useless traceback showing how the code stepped through the test framework, but nothing about how Markdown actually ran. @@ -90,7 +90,7 @@ raised by either Markdown or the test suite, then that would be reported as per a normal unit test failure with the appropriate traceback for debugging purposes. -### Syntax Test Config Settings +### Syntax Test Configuration Settings The other thing to note about the above example is that 53 tests were skipped. Those tests have been explicitly configured to be skipped as they are primarily @@ -99,17 +99,17 @@ fact, a number of different configuration settings can be set for any specific test. Each Syntax Test directory contains a `test.cfg` file in the [YAML] format. The -file may contain a separate section for each txt file named exactly as the file +file may contain a separate section for each text file named exactly as the file is named minus the file extension (i.e.; the section for a test in `foo.txt` would be `foo`). All settings are optional. Default settings for the entire directory can be set under the `DEFAULT` section (must be all caps). Any settings under a specific file section will override anything in the `DEFAULT` section for that specific test only. -Below are the config options available and the defaults used when they +Below are the configuration options available and the defaults used when they are not explicitly set. -* `normalize`: Switches whitespace normalization of the test output on or off. +* `normalize`: Switches white space normalization of the test output on or off. Defaults to `False` (off). Note: This requires that [PyTidyLib] be installed on the system. Otherwise the test will be skipped, regardless of any other settings. @@ -118,7 +118,7 @@ are not explicitly set. from other implementations. * `output_ext`: Extension of output file. Defaults to `.html`. Useful for tests from other implementations. -* Any keyword arguement accepted by the Markdown class. If not set, Markdown's +* Any keyword argument accepted by the Markdown class. If not set, Markdown's defaults are used. ## Unit Tests |