<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head><meta http-equiv="content-type" content="text/html; charset=utf-8" />
<title>[31852] trunk/src/wp-includes/formatting.php: Add more verbose inline documentation inside of `wpautop()` to more clearly explain what's going on.</title>
</head>
<body>
<style type="text/css"><!--
#msg dl.meta { border: 1px #006 solid; background: #369; padding: 6px; color: #fff; }
#msg dl.meta dt { float: left; width: 6em; font-weight: bold; }
#msg dt:after { content:':';}
#msg dl, #msg dt, #msg ul, #msg li, #header, #footer, #logmsg { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; }
#msg dl a { font-weight: bold}
#msg dl a:link { color:#fc3; }
#msg dl a:active { color:#ff0; }
#msg dl a:visited { color:#cc6; }
h3 { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; font-weight: bold; }
#msg pre { overflow: auto; background: #ffc; border: 1px #fa0 solid; padding: 6px; }
#logmsg { background: #ffc; border: 1px #fa0 solid; padding: 1em 1em 0 1em; }
#logmsg p, #logmsg pre, #logmsg blockquote { margin: 0 0 1em 0; }
#logmsg p, #logmsg li, #logmsg dt, #logmsg dd { line-height: 14pt; }
#logmsg h1, #logmsg h2, #logmsg h3, #logmsg h4, #logmsg h5, #logmsg h6 { margin: .5em 0; }
#logmsg h1:first-child, #logmsg h2:first-child, #logmsg h3:first-child, #logmsg h4:first-child, #logmsg h5:first-child, #logmsg h6:first-child { margin-top: 0; }
#logmsg ul, #logmsg ol { padding: 0; list-style-position: inside; margin: 0 0 0 1em; }
#logmsg ul { text-indent: -1em; padding-left: 1em; }#logmsg ol { text-indent: -1.5em; padding-left: 1.5em; }
#logmsg > ul, #logmsg > ol { margin: 0 0 1em 0; }
#logmsg pre { background: #eee; padding: 1em; }
#logmsg blockquote { border: 1px solid #fa0; border-left-width: 10px; padding: 1em 1em 0 1em; background: white;}
#logmsg dl { margin: 0; }
#logmsg dt { font-weight: bold; }
#logmsg dd { margin: 0; padding: 0 0 0.5em 0; }
#logmsg dd:before { content:'\00bb';}
#logmsg table { border-spacing: 0px; border-collapse: collapse; border-top: 4px solid #fa0; border-bottom: 1px solid #fa0; background: #fff; }
#logmsg table th { text-align: left; font-weight: normal; padding: 0.2em 0.5em; border-top: 1px dotted #fa0; }
#logmsg table td { text-align: right; border-top: 1px dotted #fa0; padding: 0.2em 0.5em; }
#logmsg table thead th { text-align: center; border-bottom: 1px solid #fa0; }
#logmsg table th.Corner { text-align: left; }
#logmsg hr { border: none 0; border-top: 2px dashed #fa0; height: 1px; }
#header, #footer { color: #fff; background: #636; border: 1px #300 solid; padding: 6px; }
#patch { width: 100%; }
#patch h4 {font-family: verdana,arial,helvetica,sans-serif;font-size:10pt;padding:8px;background:#369;color:#fff;margin:0;}
#patch .propset h4, #patch .binary h4 {margin:0;}
#patch pre {padding:0;line-height:1.2em;margin:0;}
#patch .diff {width:100%;background:#eee;padding: 0 0 10px 0;overflow:auto;}
#patch .propset .diff, #patch .binary .diff {padding:10px 0;}
#patch span {display:block;padding:0 10px;}
#patch .modfile, #patch .addfile, #patch .delfile, #patch .propset, #patch .binary, #patch .copfile {border:1px solid #ccc;margin:10px 0;}
#patch ins {background:#dfd;text-decoration:none;display:block;padding:0 10px;}
#patch del {background:#fdd;text-decoration:none;display:block;padding:0 10px;}
#patch .lines, .info {color:#888;background:#fff;}
--></style>
<div id="msg">
<dl class="meta" style="font-size: 105%">
<dt style="float: left; width: 6em; font-weight: bold">Revision</dt> <dd><a style="font-weight: bold" href="https://core.trac.wordpress.org/changeset/31852">31852</a><script type="application/ld+json">{"@context":"http://schema.org","@type":"EmailMessage","description":"Review this Commit","action":{"@type":"ViewAction","url":"https://core.trac.wordpress.org/changeset/31852","name":"Review Commit"}}</script></dd>
<dt style="float: left; width: 6em; font-weight: bold">Author</dt> <dd>DrewAPicture</dd>
<dt style="float: left; width: 6em; font-weight: bold">Date</dt> <dd>2015-03-20 19:46:41 +0000 (Fri, 20 Mar 2015)</dd>
</dl>
<pre style='padding-left: 1em; margin: 2em 0; border-left: 2px solid #ccc; line-height: 1.25; font-size: 105%; font-family: sans-serif'>Add more verbose inline documentation inside of `wpautop()` to more clearly explain what's going on.
Props ericlewis, johneckman, azaozz.
Fixes <a href="https://core.trac.wordpress.org/ticket/31041">#31041</a>.</pre>
<h3>Modified Paths</h3>
<ul>
<li><a href="#trunksrcwpincludesformattingphp">trunk/src/wp-includes/formatting.php</a></li>
</ul>
</div>
<div id="patch">
<h3>Diff</h3>
<a id="trunksrcwpincludesformattingphp"></a>
<div class="modfile"><h4 style="background-color: #eee; color: inherit; margin: 1em 0; padding: 1.3em; font-size: 115%">Modified: trunk/src/wp-includes/formatting.php</h4>
<pre class="diff"><span>
<span class="info" style="display: block; padding: 0 10px; color: #888">--- trunk/src/wp-includes/formatting.php 2015-03-20 19:28:30 UTC (rev 31851)
+++ trunk/src/wp-includes/formatting.php 2015-03-20 19:46:41 UTC (rev 31852)
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -360,14 +360,14 @@
</span><span class="cx" style="display: block; padding: 0 10px"> * Replaces double line-breaks with paragraph elements.
</span><span class="cx" style="display: block; padding: 0 10px"> *
</span><span class="cx" style="display: block; padding: 0 10px"> * A group of regex replaces used to identify text formatted with newlines and
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- * replace double line-breaks with HTML paragraph tags. The remaining
- * line-breaks after conversion become <<br />> tags, unless $br is set to '0'
- * or 'false'.
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ * replace double line-breaks with HTML paragraph tags. The remaining line-breaks
+ * after conversion become <<br />> tags, unless $br is set to '0' or 'false'.
</ins><span class="cx" style="display: block; padding: 0 10px"> *
</span><span class="cx" style="display: block; padding: 0 10px"> * @since 0.71
</span><span class="cx" style="display: block; padding: 0 10px"> *
</span><span class="cx" style="display: block; padding: 0 10px"> * @param string $pee The text which has to be formatted.
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- * @param bool $br Optional. If set, this will convert all remaining line-breaks after paragraphing. Default true.
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ * @param bool $br Optional. If set, this will convert all remaining line-breaks
+ * after paragraphing. Default true.
</ins><span class="cx" style="display: block; padding: 0 10px"> * @return string Text which has been converted into correct paragraph tags.
</span><span class="cx" style="display: block; padding: 0 10px"> */
</span><span class="cx" style="display: block; padding: 0 10px"> function wpautop($pee, $br = true) {
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -376,8 +376,13 @@
</span><span class="cx" style="display: block; padding: 0 10px"> if ( trim($pee) === '' )
</span><span class="cx" style="display: block; padding: 0 10px"> return '';
</span><span class="cx" style="display: block; padding: 0 10px">
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- $pee = $pee . "\n"; // just to make things a little easier, pad the end
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ // Just to make things a little easier, pad the end.
+ $pee = $pee . "\n";
</ins><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /*
+ * Pre tags shouldn't be touched by autop.
+ * Replace pre tags with placeholders and bring them back after autop.
+ */
</ins><span class="cx" style="display: block; padding: 0 10px"> if ( strpos($pee, '<pre') !== false ) {
</span><span class="cx" style="display: block; padding: 0 10px"> $pee_parts = explode( '</pre>', $pee );
</span><span class="cx" style="display: block; padding: 0 10px"> $last_pee = array_pop($pee_parts);
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -402,62 +407,102 @@
</span><span class="cx" style="display: block; padding: 0 10px">
</span><span class="cx" style="display: block; padding: 0 10px"> $pee .= $last_pee;
</span><span class="cx" style="display: block; padding: 0 10px"> }
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ // Change multiple <br>s into two line breaks, which will turn into paragraphs.
+ $pee = preg_replace('|<br />\s*<br />|', "\n\n", $pee);
</ins><span class="cx" style="display: block; padding: 0 10px">
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- $pee = preg_replace('|<br />\s*<br />|', "\n\n", $pee);
- // Space things out a little
</del><span class="cx" style="display: block; padding: 0 10px"> $allblocks = '(?:table|thead|tfoot|caption|col|colgroup|tbody|tr|td|th|div|dl|dd|dt|ul|ol|li|pre|form|map|area|blockquote|address|math|style|p|h[1-6]|hr|fieldset|legend|section|article|aside|hgroup|header|footer|nav|figure|figcaption|details|menu|summary)';
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+
+ // Add a single line break above block-level opening tags.
</ins><span class="cx" style="display: block; padding: 0 10px"> $pee = preg_replace('!(<' . $allblocks . '[^>]*>)!', "\n$1", $pee);
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+
+ // Add a double line break below block-level closing tags.
</ins><span class="cx" style="display: block; padding: 0 10px"> $pee = preg_replace('!(</' . $allblocks . '>)!', "$1\n\n", $pee);
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- $pee = str_replace(array("\r\n", "\r"), "\n", $pee); // cross-platform newlines
</del><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ // Standardize newline characters to "\n".
+ $pee = str_replace(array("\r\n", "\r"), "\n", $pee);
+
+ // Collapse line breaks before and after <option> elements so they don't get autop'd.
</ins><span class="cx" style="display: block; padding: 0 10px"> if ( strpos( $pee, '<option' ) !== false ) {
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- // no P/BR around option
</del><span class="cx" style="display: block; padding: 0 10px"> $pee = preg_replace( '|\s*<option|', '<option', $pee );
</span><span class="cx" style="display: block; padding: 0 10px"> $pee = preg_replace( '|</option>\s*|', '</option>', $pee );
</span><span class="cx" style="display: block; padding: 0 10px"> }
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /*
+ * Collapse line breaks inside <object> elements, before <param> and <embed> elements
+ * so they don't get autop'd.
+ */
</ins><span class="cx" style="display: block; padding: 0 10px"> if ( strpos( $pee, '</object>' ) !== false ) {
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- // no P/BR around param and embed
</del><span class="cx" style="display: block; padding: 0 10px"> $pee = preg_replace( '|(<object[^>]*>)\s*|', '$1', $pee );
</span><span class="cx" style="display: block; padding: 0 10px"> $pee = preg_replace( '|\s*</object>|', '</object>', $pee );
</span><span class="cx" style="display: block; padding: 0 10px"> $pee = preg_replace( '%\s*(</?(?:param|embed)[^>]*>)\s*%', '$1', $pee );
</span><span class="cx" style="display: block; padding: 0 10px"> }
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /*
+ * Collapse line breaks inside <audio> and <video> elements,
+ * before and after <source> and <track> elements.
+ */
</ins><span class="cx" style="display: block; padding: 0 10px"> if ( strpos( $pee, '<source' ) !== false || strpos( $pee, '<track' ) !== false ) {
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- // no P/BR around source and track
</del><span class="cx" style="display: block; padding: 0 10px"> $pee = preg_replace( '%([<\[](?:audio|video)[^>\]]*[>\]])\s*%', '$1', $pee );
</span><span class="cx" style="display: block; padding: 0 10px"> $pee = preg_replace( '%\s*([<\[]/(?:audio|video)[>\]])%', '$1', $pee );
</span><span class="cx" style="display: block; padding: 0 10px"> $pee = preg_replace( '%\s*(<(?:source|track)[^>]*>)\s*%', '$1', $pee );
</span><span class="cx" style="display: block; padding: 0 10px"> }
</span><span class="cx" style="display: block; padding: 0 10px">
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- $pee = preg_replace("/\n\n+/", "\n\n", $pee); // take care of duplicates
- // make paragraphs, including one at the end
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ // Remove more than two contiguous line breaks.
+ $pee = preg_replace("/\n\n+/", "\n\n", $pee);
+
+ // Split up the contents into an array of strings, separated by double line breaks.
</ins><span class="cx" style="display: block; padding: 0 10px"> $pees = preg_split('/\n\s*\n/', $pee, -1, PREG_SPLIT_NO_EMPTY);
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+
+ // Reset $pee prior to rebuilding.
</ins><span class="cx" style="display: block; padding: 0 10px"> $pee = '';
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ // Rebuild the content as a string, wrapping every bit with a <p>.
</ins><span class="cx" style="display: block; padding: 0 10px"> foreach ( $pees as $tinkle ) {
</span><span class="cx" style="display: block; padding: 0 10px"> $pee .= '<p>' . trim($tinkle, "\n") . "</p>\n";
</span><span class="cx" style="display: block; padding: 0 10px"> }
</span><span class="cx" style="display: block; padding: 0 10px">
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- $pee = preg_replace('|<p>\s*</p>|', '', $pee); // under certain strange conditions it could create a P of entirely whitespace
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ // Under certain strange conditions it could create a P of entirely whitespace.
+ $pee = preg_replace('|<p>\s*</p>|', '', $pee);
+
+ // Add a closing <p> inside <div>, <address>, or <form> tag if missing.
</ins><span class="cx" style="display: block; padding: 0 10px"> $pee = preg_replace('!<p>([^<]+)</(div|address|form)>!', "<p>$1</p></$2>", $pee);
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- $pee = preg_replace('!<p>\s*(</?' . $allblocks . '[^>]*>)\s*</p>!', "$1", $pee); // don't pee all over a tag
- $pee = preg_replace("|<p>(<li.+?)</p>|", "$1", $pee); // problem with nested lists
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+
+ // If an opening or closing block element tag is wrapped in a <p>, unwrap it.
+ $pee = preg_replace('!<p>\s*(</?' . $allblocks . '[^>]*>)\s*</p>!', "$1", $pee);
+
+ // In some cases <li> may get wrapped in <p>, fix them.
+ $pee = preg_replace("|<p>(<li.+?)</p>|", "$1", $pee);
+
+ // If a <blockquote> is wrapped with a <p>, move it inside the <blockquote>.
</ins><span class="cx" style="display: block; padding: 0 10px"> $pee = preg_replace('|<p><blockquote([^>]*)>|i', "<blockquote$1><p>", $pee);
</span><span class="cx" style="display: block; padding: 0 10px"> $pee = str_replace('</blockquote></p>', '</p></blockquote>', $pee);
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+
+ // If an opening or closing block element tag is preceded by an opening <p> tag, remove it.
</ins><span class="cx" style="display: block; padding: 0 10px"> $pee = preg_replace('!<p>\s*(</?' . $allblocks . '[^>]*>)!', "$1", $pee);
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+
+ // If an opening or closing block element tag is followed by a closing <p> tag, remove it.
</ins><span class="cx" style="display: block; padding: 0 10px"> $pee = preg_replace('!(</?' . $allblocks . '[^>]*>)\s*</p>!', "$1", $pee);
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ // Optionally insert line breaks.
</ins><span class="cx" style="display: block; padding: 0 10px"> if ( $br ) {
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ // Replace newlines that shouldn't be touched with a placeholder.
</ins><span class="cx" style="display: block; padding: 0 10px"> $pee = preg_replace_callback('/<(script|style).*?<\/\\1>/s', '_autop_newline_preservation_helper', $pee);
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- $pee = preg_replace('|(?<!<br />)\s*\n|', "<br />\n", $pee); // optionally make line breaks
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+
+ // Replace any new line characters that aren't preceded by a <br /> with a <br />.
+ $pee = preg_replace('|(?<!<br />)\s*\n|', "<br />\n", $pee);
+
+ // Replace newline placeholders with newlines.
</ins><span class="cx" style="display: block; padding: 0 10px"> $pee = str_replace('<WPPreserveNewline />', "\n", $pee);
</span><span class="cx" style="display: block; padding: 0 10px"> }
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ // If a <br /> tag is after an opening or closing block tag, remove it.
</ins><span class="cx" style="display: block; padding: 0 10px"> $pee = preg_replace('!(</?' . $allblocks . '[^>]*>)\s*<br />!', "$1", $pee);
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+
+ // If a <br /> tag is before a subset of opening or closing block tags, remove it.
</ins><span class="cx" style="display: block; padding: 0 10px"> $pee = preg_replace('!<br />(\s*</?(?:p|li|div|dl|dd|dt|th|pre|td|ul|ol)[^>]*>)!', '$1', $pee);
</span><span class="cx" style="display: block; padding: 0 10px"> $pee = preg_replace( "|\n</p>$|", '</p>', $pee );
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ // Replace placeholder <pre> tags with their original content.
</ins><span class="cx" style="display: block; padding: 0 10px"> if ( !empty($pre_tags) )
</span><span class="cx" style="display: block; padding: 0 10px"> $pee = str_replace(array_keys($pre_tags), array_values($pre_tags), $pee);
</span><span class="cx" style="display: block; padding: 0 10px">
</span></span></pre>
</div>
</div>
</body>
</html>