Changeset 3827

Timestamp:

08/18/2016 12:12:09 PM (9 years ago)

Author:

dd32

Message:

Plugin Directory: Readme parsing: When parsing the FAQ section, pull out any properly formatted (and some not-so-well-formatted) Question & Answer pairs to be displayed in a formatted fashion.

The primary method we support for FAQ entries is where the sub headings are the question, with the content following as the answer. Both = and # are supported for this:

=== FAQ ===
== Does the plugin do X? ==
Yes!
## What about Y?
Nah, Sorry!

As plugins have a wide range of contents at present, we also support plugins which have used bolded headingslike the following, note, that it must start and end the line with two asterisks.
This format isn't suggested for future usage, and is only included for the thousand or more common plugins which have used it.

=== FAQ ===
** Can I contribute to the plugin? **
Yes! Patches Welcome!

Finally, there's the plugin readme's who don't confirm to any of the above standards, or have included a paragraph of data prior to their Q&A's, for those plugins the freeform content will be prepended to the FAQ section and they won't get a properly formatted accordian-style interface.

Props obenland for the initial patch, a lot of subtle changes have been made to better handle the various readme's out there (and probably more tweaks are needed).

See #1810

File:

• sites/trunk/wordpress.org/public_html/wp-content/plugins/plugin-directory/readme/class-parser.php (modified) (6 diffs)

sites/trunk/wordpress.org/public_html/wp-content/plugins/plugin-directory/readme/class-parser.php

@@ -66 +66 @@
      */
     public $screenshots = array();
+
+    /**
+     * @var array
+     */
+    public $faq = array();
 
     /**
@@ -287 +292 @@
         // Parse out the Upgrade Notice section into it's own data.
         if ( isset( $this->sections['upgrade_notice'] ) ) {
-            $lines   = explode( "\n", $this->sections['upgrade_notice'] );
-            $version = null;
-            $current = '';
-            while ( ( $line = array_shift( $lines ) ) !== null ) {
-                $trimmed = trim( $line );
-                if ( empty( $trimmed ) ) {
-                    continue;
-                }
-
-                if ( '=' === $trimmed[0] || '#' === $trimmed[0] ) {
-                    if ( ! empty( $current ) ) {
-                        $this->upgrade_notice[ $version ] = $this->sanitize_text( trim( $current ) );
-                    }
-
-                    $current = '';
-                    $version = trim( $line, "#= \t" );
-                    continue;
-                }
-
-                $current .= $line . "\n";
-            }
-            if ( ! empty( $version ) && ! empty( $current ) ) {
-                $this->upgrade_notice[ $version ] = $this->sanitize_text( trim( $current ) );
-            }
+            $this->upgrade_notice = $this->parse_section( $this->sections['upgrade_notice'] );
+            $this->upgrade_notice = array_map( array( $this, 'sanitize_text' ), $this->upgrade_notice );
             unset( $this->sections['upgrade_notice'] );
+        }
+
+        // Display FAQs as a definition list.
+        if ( isset( $this->sections['faq'] ) ) {
+            $this->faq = $this->parse_section( $this->sections['faq'] );
+            $this->sections['faq'] = '';
         }
 
@@ -317 +306 @@
         $this->sections       = array_map( array( $this, 'parse_markdown' ), $this->sections );
         $this->upgrade_notice = array_map( array( $this, 'parse_markdown' ), $this->upgrade_notice );
+        $this->faq            = array_map( array( $this, 'parse_markdown' ), $this->faq );
 
         // Sanitize and trim the short_description to match requirements.
@@ -333 +323 @@
             }
             unset( $this->sections['screenshots'] );
+        }
+
+        if ( ! empty( $this->faq ) ) {
+            // If the FAQ contained data we couldn't parse, we'll treat it as freeform and display it before any questions which are found.
+            if ( isset( $this->faq[''] ) ) {
+                $this->sections['faq'] .= $this->faq[''];
+                unset( $this->faq[''] );
+            }
+
+            if ( $this->faq ) {
+                $this->sections['faq'] .= "\n<dl>\n";
+                foreach ( $this->faq as $question => $answer ) {
+                    $this->sections['faq'] .= "<dt>{$question}</dt>\n<dd>{$answer}</dd>\n";
+                }
+                $this->sections['faq'] .= "\n</dl>\n";
+            }
         }
 
@@ -414 +420 @@
             'ul'         => true,
             'ol'         => true,
+            'dl'         => true,
+            'dt'         => true,
+            'dd'         => true,
             'li'         => true,
             'h3'         => true,
@@ -496 +505 @@
 
     /**
+     * Parses a slice of lines from the file into an array of Heading => Content.
+     *
+     * We assume that every heading encountered is a new item, and not a sub heading.
+     * We support headings which are either `= Heading`, `# Heading` or `** Heading`.
+     *
+     * @param string|array $lines The lines of the section to parse.
+     * @return array
+     */
+    protected function parse_section( $lines ) {
+        $key = $value = '';
+        $return = array();
+
+        if ( ! is_array( $lines ) ) {
+            $lines = explode( "\n", $lines );
+        }
+
+        while ( ( $line = array_shift( $lines ) ) !== null ) {
+            $trimmed = trim( $line );
+            if ( ! $trimmed ) {
+                $value .= "\n";
+                continue;
+            }
+
+            // Normal headings (##.. == ... ==) are matched if they exist, Bold is only used if it starts and ends the line.
+            if ( $trimmed[0] == '#' || $trimmed[0] == '=' || ( substr( $trimmed, 0, 2 ) == '**' && substr( $trimmed, -2 ) == '**' ) ) {
+                if ( $value ) {
+                    $return[ $key ] = trim( $value );
+                }
+
+                $value = '';
+                // Trim off the first character of the line, as we know that's the heading style we're expecting to remove.
+                $key   = trim( $line, $trimmed[0] . " \t" );
+                continue;
+            }
+
+            $value .= $line . "\n";
+        }
+
+        if ( $key || $value ) {
+            $return[ $key ] = trim( $value );
+        }
+
+        return $return;
+    }
+
+    /**
      * @param string $text
      * @return string