Make WordPress Core


Ignore:
Timestamp:
03/20/2015 07:46:41 PM (9 years ago)
Author:
DrewAPicture
Message:

Add more verbose inline documentation inside of wpautop() to more clearly explain what's going on.

Props ericlewis, johneckman, azaozz.
Fixes #31041.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/formatting.php

    r31847 r31852  
    361361 *
    362362 * A group of regex replaces used to identify text formatted with newlines and
    363  * replace double line-breaks with HTML paragraph tags. The remaining
    364  * line-breaks after conversion become <<br />> tags, unless $br is set to '0'
    365  * or 'false'.
     363 * replace double line-breaks with HTML paragraph tags. The remaining line-breaks
     364 * after conversion become <<br />> tags, unless $br is set to '0' or 'false'.
    366365 *
    367366 * @since 0.71
    368367 *
    369368 * @param string $pee The text which has to be formatted.
    370  * @param bool $br Optional. If set, this will convert all remaining line-breaks after paragraphing. Default true.
     369 * @param bool   $br  Optional. If set, this will convert all remaining line-breaks
     370 *                    after paragraphing. Default true.
    371371 * @return string Text which has been converted into correct paragraph tags.
    372372 */
     
    377377        return '';
    378378
    379     $pee = $pee . "\n"; // just to make things a little easier, pad the end
    380 
     379    // Just to make things a little easier, pad the end.
     380    $pee = $pee . "\n";
     381
     382    /*
     383     * Pre tags shouldn't be touched by autop.
     384     * Replace pre tags with placeholders and bring them back after autop.
     385     */
    381386    if ( strpos($pee, '<pre') !== false ) {
    382387        $pee_parts = explode( '</pre>', $pee );
     
    403408        $pee .= $last_pee;
    404409    }
    405 
     410    // Change multiple <br>s into two line breaks, which will turn into paragraphs.
    406411    $pee = preg_replace('|<br />\s*<br />|', "\n\n", $pee);
    407     // Space things out a little
     412
    408413    $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)';
     414
     415    // Add a single line break above block-level opening tags.
    409416    $pee = preg_replace('!(<' . $allblocks . '[^>]*>)!', "\n$1", $pee);
     417
     418    // Add a double line break below block-level closing tags.
    410419    $pee = preg_replace('!(</' . $allblocks . '>)!', "$1\n\n", $pee);
    411     $pee = str_replace(array("\r\n", "\r"), "\n", $pee); // cross-platform newlines
    412 
     420
     421    // Standardize newline characters to "\n".
     422    $pee = str_replace(array("\r\n", "\r"), "\n", $pee);
     423
     424    // Collapse line breaks before and after <option> elements so they don't get autop'd.
    413425    if ( strpos( $pee, '<option' ) !== false ) {
    414         // no P/BR around option
    415426        $pee = preg_replace( '|\s*<option|', '<option', $pee );
    416427        $pee = preg_replace( '|</option>\s*|', '</option>', $pee );
    417428    }
    418429
     430    /*
     431     * Collapse line breaks inside <object> elements, before <param> and <embed> elements
     432     * so they don't get autop'd.
     433     */
    419434    if ( strpos( $pee, '</object>' ) !== false ) {
    420         // no P/BR around param and embed
    421435        $pee = preg_replace( '|(<object[^>]*>)\s*|', '$1', $pee );
    422436        $pee = preg_replace( '|\s*</object>|', '</object>', $pee );
     
    424438    }
    425439
     440    /*
     441     * Collapse line breaks inside <audio> and <video> elements,
     442     * before and after <source> and <track> elements.
     443     */
    426444    if ( strpos( $pee, '<source' ) !== false || strpos( $pee, '<track' ) !== false ) {
    427         // no P/BR around source and track
    428445        $pee = preg_replace( '%([<\[](?:audio|video)[^>\]]*[>\]])\s*%', '$1', $pee );
    429446        $pee = preg_replace( '%\s*([<\[]/(?:audio|video)[>\]])%', '$1', $pee );
     
    431448    }
    432449
    433     $pee = preg_replace("/\n\n+/", "\n\n", $pee); // take care of duplicates
    434     // make paragraphs, including one at the end
     450    // Remove more than two contiguous line breaks.
     451    $pee = preg_replace("/\n\n+/", "\n\n", $pee);
     452
     453    // Split up the contents into an array of strings, separated by double line breaks.
    435454    $pees = preg_split('/\n\s*\n/', $pee, -1, PREG_SPLIT_NO_EMPTY);
     455
     456    // Reset $pee prior to rebuilding.
    436457    $pee = '';
    437458
     459    // Rebuild the content as a string, wrapping every bit with a <p>.
    438460    foreach ( $pees as $tinkle ) {
    439461        $pee .= '<p>' . trim($tinkle, "\n") . "</p>\n";
    440462    }
    441463
    442     $pee = preg_replace('|<p>\s*</p>|', '', $pee); // under certain strange conditions it could create a P of entirely whitespace
     464    // Under certain strange conditions it could create a P of entirely whitespace.
     465    $pee = preg_replace('|<p>\s*</p>|', '', $pee);
     466
     467    // Add a closing <p> inside <div>, <address>, or <form> tag if missing.
    443468    $pee = preg_replace('!<p>([^<]+)</(div|address|form)>!', "<p>$1</p></$2>", $pee);
    444     $pee = preg_replace('!<p>\s*(</?' . $allblocks . '[^>]*>)\s*</p>!', "$1", $pee); // don't pee all over a tag
    445     $pee = preg_replace("|<p>(<li.+?)</p>|", "$1", $pee); // problem with nested lists
     469   
     470    // If an opening or closing block element tag is wrapped in a <p>, unwrap it.
     471    $pee = preg_replace('!<p>\s*(</?' . $allblocks . '[^>]*>)\s*</p>!', "$1", $pee);
     472   
     473    // In some cases <li> may get wrapped in <p>, fix them.
     474    $pee = preg_replace("|<p>(<li.+?)</p>|", "$1", $pee);
     475   
     476    // If a <blockquote> is wrapped with a <p>, move it inside the <blockquote>.
    446477    $pee = preg_replace('|<p><blockquote([^>]*)>|i', "<blockquote$1><p>", $pee);
    447478    $pee = str_replace('</blockquote></p>', '</p></blockquote>', $pee);
     479   
     480    // If an opening or closing block element tag is preceded by an opening <p> tag, remove it.
    448481    $pee = preg_replace('!<p>\s*(</?' . $allblocks . '[^>]*>)!', "$1", $pee);
     482   
     483    // If an opening or closing block element tag is followed by a closing <p> tag, remove it.
    449484    $pee = preg_replace('!(</?' . $allblocks . '[^>]*>)\s*</p>!', "$1", $pee);
    450485
     486    // Optionally insert line breaks.
    451487    if ( $br ) {
     488        // Replace newlines that shouldn't be touched with a placeholder.
    452489        $pee = preg_replace_callback('/<(script|style).*?<\/\\1>/s', '_autop_newline_preservation_helper', $pee);
    453         $pee = preg_replace('|(?<!<br />)\s*\n|', "<br />\n", $pee); // optionally make line breaks
     490
     491        // Replace any new line characters that aren't preceded by a <br /> with a <br />.
     492        $pee = preg_replace('|(?<!<br />)\s*\n|', "<br />\n", $pee);
     493
     494        // Replace newline placeholders with newlines.
    454495        $pee = str_replace('<WPPreserveNewline />', "\n", $pee);
    455496    }
    456497
     498    // If a <br /> tag is after an opening or closing block tag, remove it.
    457499    $pee = preg_replace('!(</?' . $allblocks . '[^>]*>)\s*<br />!', "$1", $pee);
     500   
     501    // If a <br /> tag is before a subset of opening or closing block tags, remove it.
    458502    $pee = preg_replace('!<br />(\s*</?(?:p|li|div|dl|dd|dt|th|pre|td|ul|ol)[^>]*>)!', '$1', $pee);
    459503    $pee = preg_replace( "|\n</p>$|", '</p>', $pee );
    460504
     505    // Replace placeholder <pre> tags with their original content.
    461506    if ( !empty($pre_tags) )
    462507        $pee = str_replace(array_keys($pre_tags), array_values($pre_tags), $pee);
Note: See TracChangeset for help on using the changeset viewer.