diff options
Diffstat (limited to 'lib/php-markdown/README.markdown')
| -rw-r--r-- | lib/php-markdown/README.markdown | 737 |
1 files changed, 0 insertions, 737 deletions
diff --git a/lib/php-markdown/README.markdown b/lib/php-markdown/README.markdown deleted file mode 100644 index 565fde30f..000000000 --- a/lib/php-markdown/README.markdown +++ /dev/null @@ -1,737 +0,0 @@ -PHP Markdown Extra -================== - -Version 1.2.3 - Wed 31 Dec 2008 - -by Michel Fortin -<http://www.michelf.com/> - -Additional features and fixes by Henrik Paul -<http://github.com/wolfie/php-markdown/tree/extra> - -based on Markdown by John Gruber -<http://daringfireball.net/> - - -Introduction ------------- - -This is a special version of PHP Markdown with extra features. See -<http://www.michelf.com/projects/php-markdown/extra/> for details. - -Markdown is a text-to-HTML conversion tool for web writers. Markdown -allows you to write using an easy-to-read, easy-to-write plain text -format, then convert it to structurally valid XHTML (or HTML). - -"Markdown" is two things: a plain text markup syntax, and a software -tool, written in Perl, that converts the plain text markup to HTML. -PHP Markdown is a port to PHP of the original Markdown program by -John Gruber. - -PHP Markdown can work as a plug-in for WordPress and bBlog, as a -modifier for the Smarty templating engine, or as a remplacement for -textile formatting in any software that support textile. - -Full documentation of Markdown's syntax is available on John's -Markdown page: <http://daringfireball.net/projects/markdown/> - - -Installation and Requirement ----------------------------- - -PHP Markdown requires PHP version 4.0.5 or later. - - -### WordPress ### - -PHP Markdown works with [WordPress][wp], version 1.2 or later. - - [wp]: http://wordpress.org/ - -1. To use PHP Markdown with WordPress, place the "makrdown.php" file - in the "plugins" folder. This folder is located inside - "wp-content" at the root of your site: - - (site home)/wp-content/plugins/ - -2. Activate the plugin with the administrative interface of - WordPress. In the "Plugins" section you will now find Markdown. - To activate the plugin, click on the "Activate" button on the - same line than Markdown. Your entries will now be formatted by - PHP Markdown. - -3. To post Markdown content, you'll first have to disable the - "visual" editor in the User section of WordPress. - -You can configure PHP Markdown to not apply to the comments on your -WordPress weblog. See the "Configuration" section below. - -It is not possible at this time to apply a different set of -filters to different entries. All your entries will be formated by -PHP Markdown. This is a limitation of WordPress. If your old entries -are written in HTML (as opposed to another formatting syntax, like -Textile), they'll probably stay fine after installing Markdown. - - -### bBlog ### - -PHP Markdown also works with [bBlog][bb]. - - [bb]: http://www.bblog.com/ - -To use PHP Markdown with bBlog, rename "markdown.php" to -"modifier.markdown.php" and place the file in the "bBlog_plugins" -folder. This folder is located inside the "bblog" directory of -your site, like this: - - (site home)/bblog/bBlog_plugins/modifier.markdown.php - -Select "Markdown" as the "Entry Modifier" when you post a new -entry. This setting will only apply to the entry you are editing. - - -### Replacing Textile in TextPattern ### - -[TextPattern][tp] use [Textile][tx] to format your text. You can -replace Textile by Markdown in TextPattern without having to change -any code by using the *Texitle Compatibility Mode*. This may work -with other software that expect Textile too. - - [tx]: http://www.textism.com/tools/textile/ - [tp]: http://www.textpattern.com/ - -1. Rename the "markdown.php" file to "classTextile.php". This will - make PHP Markdown behave as if it was the actual Textile parser. - -2. Replace the "classTextile.php" file TextPattern installed in your - web directory. It can be found in the "lib" directory: - - (site home)/textpattern/lib/ - -Contrary to Textile, Markdown does not convert quotes to curly ones -and does not convert multiple hyphens (`--` and `---`) into en- and -em-dashes. If you use PHP Markdown in Textile Compatibility Mode, you -can solve this problem by installing the "smartypants.php" file from -[PHP SmartyPants][psp] beside the "classTextile.php" file. The Textile -Compatibility Mode function will use SmartyPants automatically without -further modification. - - [psp]: http://www.michelf.com/projects/php-smartypants/ - - -### In Your Own Programs ### - -You can use PHP Markdown easily in your current PHP program. Simply -include the file and then call the Markdown function on the text you -want to convert: - - include_once "markdown.php"; - $my_html = Markdown($my_text); - -If you wish to use PHP Markdown with another text filter function -built to parse HTML, you should filter the text *after* the Markdown -function call. This is an example with [PHP SmartyPants][psp]: - - $my_html = SmartyPants(Markdown($my_text)); - - -### With Smarty ### - -If your program use the [Smarty][sm] template engine, PHP Markdown -can now be used as a modifier for your templates. Rename "markdown.php" -to "modifier.markdown.php" and put it in your smarty plugins folder. - - [sm]: http://smarty.php.net/ - -If you are using MovableType 3.1 or later, the Smarty plugin folder is -located at `(MT CGI root)/php/extlib/smarty/plugins`. This will allow -Markdown to work on dynamic pages. - - -### Updating Markdown in Other Programs ### - -Many web applications now ship with PHP Markdown, or have plugins to -perform the conversion to HTML. You can update PHP Markdown -- or -replace it with PHP Markdown Extra -- in many of these programs by -swapping the old "markdown.php" file for the new one. - -Here is a short non-exhaustive list of some programs and where they -hide the "markdown.php" file. - -| Program | Path to Markdown -| ------- | ---------------- -| [Pivot][] | `(site home)/pivot/includes/markdown/` - -If you're unsure if you can do this with your application, ask the -developer, or wait for the developer to update his application or -plugin with the new version of PHP Markdown. - - [Pivot]: http://pivotlog.net/ - - -Configuration -------------- - -By default, PHP Markdown produces XHTML output for tags with empty -elements. E.g.: - - <br /> - -Markdown can be configured to produce HTML-style tags; e.g.: - - <br> - -To do this, you must edit the "MARKDOWN_EMPTY_ELEMENT_SUFFIX" -definition below the "Global default settings" header at the start of -the "markdown.php" file. - - -### WordPress-Specific Settings ### - -By default, the Markdown plugin applies to both posts and comments on -your WordPress weblog. To deactivate one or the other, edit the -`MARKDOWN_WP_POSTS` or `MARKDOWN_WP_COMMENTS` definitions under the -"WordPress settings" header at the start of the "markdown.php" file. - - -Bugs ----- - -To file bug reports please send email to: -<michel.fortin@michelf.com> - -Please include with your report: (1) the example input; (2) the output you -expected; (3) the output PHP Markdown actually produced. - - -Version History ---------------- - -Extra 1.2.3 (31 Dec 2008): - -* In WordPress pages featuring more than one post, footnote id prefixes are - now automatically applied with the current post ID to avoid clashes - between footnotes belonging to different posts. - -* Fix for a bug introduced in Extra 1.2 where block-level HTML tags where - not detected correctly, thus the addition of erroneous `<p>` tags and - interpretation of their content as Markdown-formatted instead of - HTML-formatted. - - -Extra 1.2.2 (21 Jun 2008): - -* Fixed a problem where abbreviation definitions, footnote - definitions and link references were stripped inside - fenced code blocks. - -* Fixed a bug where characters such as `"` in abbreviation - definitions weren't properly encoded to HTML entities. - -* Fixed a bug where double quotes `"` were not correctly encoded - as HTML entities when used inside a footnote reference id. - - -1.0.1m (21 Jun 2008): - -* Lists can now have empty items. - -* Rewrote the emphasis and strong emphasis parser to fix some issues - with odly placed and overlong markers. - - -Extra 1.2.1 (27 May 2008): - -* Fixed a problem where Markdown headers and horizontal rules were - transformed into their HTML equivalent inside fenced code blocks. - - -Extra 1.2 (11 May 2008): - -* Added fenced code block syntax which don't require indentation - and can start and end with blank lines. A fenced code block - starts with a line of consecutive tilde (~) and ends on the - next line with the same number of consecutive tilde. Here's an - example: - - ~~~~~~~~~~~~ - Hello World! - ~~~~~~~~~~~~ - -* Rewrote parts of the HTML block parser to better accomodate - fenced code blocks. - -* Footnotes may now be referenced from within another footnote. - -* Added programatically-settable parser property `predef_attr` for - predefined attribute definitions. - -* Fixed an issue where an indented code block preceded by a blank - line containing some other whitespace would confuse the HTML - block parser into creating an HTML block when it should have - been code. - - -1.0.1l (11 May 2008): - -* Now removing the UTF-8 BOM at the start of a document, if present. - -* Now accepting capitalized URI schemes (such as HTTP:) in automatic - links, such as `<HTTP://EXAMPLE.COM/>`. - -* Fixed a problem where `<hr@example.com>` was seen as a horizontal - rule instead of an automatic link. - -* Fixed an issue where some characters in Markdown-generated HTML - attributes weren't properly escaped with entities. - -* Fix for code blocks as first element of a list item. Previously, - this didn't create any code block for item 2: - - * Item 1 (regular paragraph) - - * Item 2 (code block) - -* A code block starting on the second line of a document wasn't seen - as a code block. This has been fixed. - -* Added programatically-settable parser properties `predef_urls` and - `predef_titles` for predefined URLs and titles for reference-style - links. To use this, your PHP code must call the parser this way: - - $parser = new Markdwon_Parser; - $parser->predef_urls = array('linkref' => 'http://example.com'); - $html = $parser->transform($text); - - You can then use the URL as a normal link reference: - - [my link][linkref] - [my link][linkRef] - - Reference names in the parser properties *must* be lowercase. - Reference names in the Markdown source may have any case. - -* Added `setup` and `teardown` methods which can be used by subclassers - as hook points to arrange the state of some parser variables before and - after parsing. - - -Extra 1.1.7 (26 Sep 2007): - -1.0.1k (26 Sep 2007): - -* Fixed a problem introduced in 1.0.1i where three or more identical - uppercase letters, as well as a few other symbols, would trigger - a horizontal line. - - -Extra 1.1.6 (4 Sep 2007): - -1.0.1j (4 Sep 2007): - -* Fixed a problem introduced in 1.0.1i where the closing `code` and - `pre` tags at the end of a code block were appearing in the wrong - order. - -* Overriding configuration settings by defining constants from an - external before markdown.php is included is now possible without - producing a PHP warning. - - -Extra 1.1.5 (31 Aug 2007): - -1.0.1i (31 Aug 2007): - -* Fixed a problem where an escaped backslash before a code span - would prevent the code span from being created. This should now - work as expected: - - Litteral backslash: \\`code span` - -* Overall speed improvements, especially with long documents. - - -Extra 1.1.4 (3 Aug 2007): - -1.0.1h (3 Aug 2007): - -* Added two properties (`no_markup` and `no_entities`) to the parser - allowing HTML tags and entities to be disabled. - -* Fix for a problem introduced in 1.0.1g where posting comments in - WordPress would trigger PHP warnings and cause some markup to be - incorrectly filtered by the kses filter in WordPress. - - -Extra 1.1.3 (3 Jul 2007): - -* Fixed a performance problem when parsing some invalid HTML as an HTML - block which was resulting in too much recusion and a segmentation fault - for long documents. - -* The markdown="" attribute now accepts unquoted values. - -* Fixed an issue where underscore-emphasis didn't work when applied on the - first or the last word of an element having the markdown="1" or - markdown="span" attribute set unless there was some surrounding whitespace. - This didn't work: - - <p markdown="1">_Hello_ _world_</p> - - Now it does produce emphasis as expected. - -* Fixed an issue preventing footnotes from working when the parser's - footnote id prefix variable (fn_id_prefix) is not empty. - -* Fixed a performance problem where the regular expression for strong - emphasis introduced in version 1.1 could sometime be long to process, - give slightly wrong results, and in some circumstances could remove - entirely the content for a whole paragraph. - -* Fixed an issue were abbreviations tags could be incorrectly added - inside URLs and title of links. - -* Placing footnote markers inside a link, resulting in two nested links, is - no longer allowed. - - -1.0.1g (3 Jul 2007): - -* Fix for PHP 5 compiled without the mbstring module. Previous fix to - calculate the length of UTF-8 strings in `detab` when `mb_strlen` is - not available was only working with PHP 4. - -* Fixed a problem with WordPress 2.x where full-content posts in RSS feeds - were not processed correctly by Markdown. - -* Now supports URLs containing literal parentheses for inline links - and images, such as: - - [WIMP](http://en.wikipedia.org/wiki/WIMP_(computing)) - - Such parentheses may be arbitrarily nested, but must be - balanced. Unbalenced parentheses are allowed however when the URL - when escaped or when the URL is enclosed in angle brakets `<>`. - -* Fixed a performance problem where the regular expression for strong - emphasis introduced in version 1.0.1d could sometime be long to process, - give slightly wrong results, and in some circumstances could remove - entirely the content for a whole paragraph. - -* Some change in version 1.0.1d made possible the incorrect nesting of - anchors within each other. This is now fixed. - -* Fixed a rare issue where certain MD5 hashes in the content could - be changed to their corresponding text. For instance, this: - - The MD5 value for "+" is "26b17225b626fb9238849fd60eabdf60". - - was incorrectly changed to this in previous versions of PHP Markdown: - - <p>The MD5 value for "+" is "+".</p> - -* Now convert escaped characters to their numeric character - references equivalent. - - This fix an integration issue with SmartyPants and backslash escapes. - Since Markdown and SmartyPants have some escapable characters in common, - it was sometime necessary to escape them twice. Previously, two - backslashes were sometime required to prevent Markdown from "eating" the - backslash before SmartyPants sees it: - - Here are two hyphens: \\-- - - Now, only one backslash will do: - - Here are two hyphens: \-- - - -Extra 1.1.2 (7 Feb 2007) - -* Fixed an issue where headers preceded too closely by a paragraph - (with no blank line separating them) where put inside the paragraph. - -* Added the missing TextileRestricted method that was added to regular - PHP Markdown since 1.0.1d but which I forgot to add to Extra. - - -1.0.1f (7 Feb 2007): - -* Fixed an issue with WordPress where manually-entered excerpts, but - not the auto-generated ones, would contain nested paragraphs. - -* Fixed an issue introduced in 1.0.1d where headers and blockquotes - preceded too closely by a paragraph (not separated by a blank line) - where incorrectly put inside the paragraph. - -* Fixed an issue introduced in 1.0.1d in the tokenizeHTML method where - two consecutive code spans would be merged into one when together they - form a valid tag in a multiline paragraph. - -* Fixed an long-prevailing issue where blank lines in code blocks would - be doubled when the code block is in a list item. - - This was due to the list processing functions relying on artificially - doubled blank lines to correctly determine when list items should - contain block-level content. The list item processing model was thus - changed to avoid the need for double blank lines. - -* Fixed an issue with `<% asp-style %>` instructions used as inline - content where the opening `<` was encoded as `<`. - -* Fixed a parse error occuring when PHP is configured to accept - ASP-style delimiters as boundaries for PHP scripts. - -* Fixed a bug introduced in 1.0.1d where underscores in automatic links - got swapped with emphasis tags. - - -Extra 1.1.1 (28 Dec 2006) - -* Fixed a problem where whitespace at the end of the line of an atx-style - header would cause tailing `#` to appear as part of the header's content. - This was caused by a small error in the regex that handles the definition - for the id attribute in PHP Markdown Extra. - -* Fixed a problem where empty abbreviations definitions would eat the - following line as its definition. - -* Fixed an issue with calling the Markdown parser repetitivly with text - containing footnotes. The footnote hashes were not reinitialized properly. - - -1.0.1e (28 Dec 2006) - -* Added support for internationalized domain names for email addresses in - automatic link. Improved the speed at which email addresses are converted - to entities. Thanks to Milian Wolff for his optimisations. - -* Made deterministic the conversion to entities of email addresses in - automatic links. This means that a given email address will always be - encoded the same way. - -* PHP Markdown will now use its own function to calculate the length of an - UTF-8 string in `detab` when `mb_strlen` is not available instead of - giving a fatal error. - - -Extra 1.1 (1 Dec 2006) - -* Added a syntax for footnotes. - -* Added an experimental syntax to define abbreviations. - - -1.0.1d (1 Dec 2006) - -* Fixed a bug where inline images always had an empty title attribute. The - title attribute is now present only when explicitly defined. - -* Link references definitions can now have an empty title, previously if the - title was defined but left empty the link definition was ignored. This can - be useful if you want an empty title attribute in images to hide the - tooltip in Internet Explorer. - -* Made `detab` aware of UTF-8 characters. UTF-8 multi-byte sequences are now - correctly mapped to one character instead of the number of bytes. - -* Fixed a small bug with WordPress where WordPress' default filter `wpautop` - was not properly deactivated on comment text, resulting in hard line breaks - where Markdown do not prescribes them. - -* Added a `TextileRestrited` method to the textile compatibility mode. There - is no restriction however, as Markdown does not have a restricted mode at - this point. This should make PHP Markdown work again in the latest - versions of TextPattern. - -* Converted PHP Markdown to a object-oriented design. - -* Changed span and block gamut methods so that they loop over a - customizable list of methods. This makes subclassing the parser a more - interesting option for creating syntax extensions. - -* Also added a "document" gamut loop which can be used to hook document-level - methods (like for striping link definitions). - -* Changed all methods which were inserting HTML code so that they now return - a hashed representation of the code. New methods `hashSpan` and `hashBlock` - are used to hash respectivly span- and block-level generated content. This - has a couple of significant effects: - - 1. It prevents invalid nesting of Markdown-generated elements which - could occur occuring with constructs like `*something [link*][1]`. - 2. It prevents problems occuring with deeply nested lists on which - paragraphs were ill-formed. - 3. It removes the need to call `hashHTMLBlocks` twice during the the - block gamut. - - Hashes are turned back to HTML prior output. - -* Made the block-level HTML parser smarter using a specially-crafted regular - expression capable of handling nested tags. - -* Solved backtick issues in tag attributes by rewriting the HTML tokenizer to - be aware of code spans. All these lines should work correctly now: - - <span attr='`ticks`'>bar</span> - <span attr='``double ticks``'>bar</span> - `<test a="` content of attribute `">` - -* Changed the parsing of HTML comments to match simply from `<!--` to `-->` - instead using of the more complicated SGML-style rule with paired `--`. - This is how most browsers parse comments and how XML defines them too. - -* `<address>` has been added to the list of block-level elements and is now - treated as an HTML block instead of being wrapped within paragraph tags. - -* Now only trim trailing newlines from code blocks, instead of trimming - all trailing whitespace characters. - -* Fixed bug where this: - - [text](http://m.com "title" ) - - wasn't working as expected, because the parser wasn't allowing for spaces - before the closing paren. - -* Filthy hack to support markdown='1' in div tags. - -* _DoAutoLinks() now supports the 'dict://' URL scheme. - -* PHP- and ASP-style processor instructions are now protected as - raw HTML blocks. - - <? ... ?> - <% ... %> - -* Fix for escaped backticks still triggering code spans: - - There are two raw backticks here: \` and here: \`, not a code span - - -Extra 1.0 - 5 September 2005 - -* Added support for setting the id attributes for headers like this: - - Header 1 {#header1} - ======== - - ## Header 2 ## {#header2} - - This only work only for headers for now. - -* Tables will now work correctly as the first element of a definition - list. For example, this input: - - Term - - : Header | Header - ------- | ------- - Cell | Cell - - used to produce no definition list and a table where the first - header was named ": Header". This is now fixed. - -* Fix for a problem where a paragraph following a table was not - placed between `<p>` tags. - - -Extra 1.0b4 - 1 August 2005 - -* Fixed some issues where whitespace around HTML blocks were trigging - empty paragraph tags. - -* Fixed an HTML block parsing issue that would cause a block element - following a code span or block with unmatched opening bracket to be - placed inside a paragraph. - -* Removed some PHP notices that could appear when parsing definition - lists and tables with PHP notice reporting flag set. - - -Extra 1.0b3 - 29 July 2005 - -* Definition lists now require a blank line before each term. Solves - an ambiguity where the last line of lazy-indented definitions could - be mistaken by PHP Markdown as a new term in the list. - -* Definition lists now support multiple terms per definition. - -* Some special tags were replaced in the output by their md5 hash - key. Things such as this now work as expected: - - ## Header <?php echo $number ?> ## - - -Extra 1.0b2 - 26 July 2005 - -* Definition lists can now take two or more definitions for one term. - This should have been the case before, but a bug prevented this - from working right. - -* Fixed a problem where single column table with a pipe only at the - end where not parsed as table. Here is such a table: - - | header - | ------ - | cell - -* Fixed problems with empty cells in the first column of a table with - no leading pipe, like this one: - - header | header - ------ | ------ - | cell - -* Code spans containing pipes did not within a table. This is now - fixed by parsing code spans before splitting rows into cells. - -* Added the pipe character to the backlash escape character lists. - -Extra 1.0b1 (25 Jun 2005) - -* First public release of PHP Markdown Extra. - - -Copyright and License ---------------------- - -Copyright (c) 2004-2005 Michel Fortin -<http://www.michelf.com/> -All rights reserved. - -Additional features and fixes by Henrik Paul -<http://github.com/wolfie/php-markdown/tree/extra> - -Based on Markdown -Copyright (c) 2003-2005 John Gruber -<http://daringfireball.net/> -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: - -* Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - -* Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the - distribution. - -* Neither the name "Markdown" nor the names of its contributors may - be used to endorse or promote products derived from this software - without specific prior written permission. - -This software is provided by the copyright holders and contributors "as -is" and any express or implied warranties, including, but not limited -to, the implied warranties of merchantability and fitness for a -particular purpose are disclaimed. In no event shall the copyright owner -or contributors be liable for any direct, indirect, incidental, special, -exemplary, or consequential damages (including, but not limited to, -procurement of substitute goods or services; loss of use, data, or -profits; or business interruption) however caused and on any theory of -liability, whether in contract, strict liability, or tort (including -negligence or otherwise) arising in any way out of the use of this -software, even if advised of the possibility of such damage. |