aboutsummaryrefslogtreecommitdiffstats
path: root/lib/php-markdown/README
diff options
context:
space:
mode:
Diffstat (limited to 'lib/php-markdown/README')
-rw-r--r--lib/php-markdown/README737
1 files changed, 737 insertions, 0 deletions
diff --git a/lib/php-markdown/README b/lib/php-markdown/README
new file mode 100644
index 0000000..565fde3
--- /dev/null
+++ b/lib/php-markdown/README
@@ -0,0 +1,737 @@
+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 `&lt;`.
+
+* 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.
generated by cgit v1.2.1 (git 2.21.0) at 2024-11-27 05:21:29 +0000