Changeset 10068

Timestamp:

07/13/2020 10:40:31 PM (6 years ago)

Author:

coffee2code

Message:

Developer theme: Convert lists (defined using * or - for items) appearing in descriptions into actual HTML lists.

Props ocean90, coffee2code.
See #5304.

Location:

sites/trunk/wordpress.org/public_html/wp-content/themes/pub/wporg-developer

Files:

• inc/formatting.php (modified) (3 diffs)
• scss/main.scss (modified) (1 diff)
• stylesheets/main.css (modified) (2 diffs)

sites/trunk/wordpress.org/public_html/wp-content/themes/pub/wporg-developer/inc/formatting.php

@@ -40 +40 @@
                 add_filter( 'devhub-format-description', array( __CLASS__, 'fix_param_hash_formatting' ), 9 );
                 add_filter( 'devhub-format-description', array( __CLASS__, 'fix_param_description_html_as_code' ) );
+                add_filter( 'devhub-format-description', array( __CLASS__, 'convert_lists_to_markup' ) );
 
                 add_filter( 'devhub-format-hash-param-description', array( __CLASS__, 'autolink_references' ) );
@@ -316 +317 @@
                 foreach ( $allowable_tags as $tag ) {
                         $text = str_replace( array( "&lt;{$tag}&gt;", "&lt;/{$tag}&gt;" ), array( "<{$tag}>", "</{$tag}>" ), $text );
-                }
-
-                // Convert asterisks to a list.
-                // Inline lists in param descriptions aren't handled by parser.
-                // Example: https://developer.wordpress.org/reference/functions/add_menu_page/
-                if ( false !== strpos( $text, ' * ' ) )  {
-                        // Display as simple plaintext list.
-                        $text = str_replace( ' * ', '<br /> * ', $text );
                 }
 
@@ -485 +478 @@
 
         /**
+         * Converts simple Markdown-like lists into list markup.
+         *
+         * Necessary in cases like hash param descriptions which don't see Markdown
+         * list processing during parsing.
+         *
+         * Recognizes lists where list items are denoted with an asterisk or dash.
+         *
+         * Does not handle nesting of lists.
+         *
+         * @param string $text The text to process for lists.
+         * @return string
+         */
+        public static function convert_lists_to_markup( $text ) {
+                $inline_list = false;
+                $li = '<br /> * ';
+
+                // Convert asterisks to a list.
+                // Example: https://developer.wordpress.org/reference/functions/add_menu_page/
+                if ( false !== strpos( $text, ' * ' ) )  {
+                        // Display as simple plaintext list.
+                        $text = str_replace( ' * ', "\n" . $li, $text );
+                        $inline_list = true;
+                }
+
+                // Convert dashes to a list.
+                // Example: https://developer.wordpress.org/reference/classes/wp_term_query/__construct/
+                // Example: https://developer.wordpress.org/reference/hooks/password_change_email/
+                if ( false !== strpos( $text, ' - ' ) )  {
+                        // Display as simple plaintext list.
+                        $text = str_replace( ' - ', "\n" . $li, $text );
+                        $inline_list = true;
+                }
+
+                // If list detected.
+                if ( $inline_list ) {
+                        // Replace first item, ensuring the opening 'ul' tag is prepended.
+                        $text = preg_replace( '~^' . preg_quote( $li ) . '(.+)$~mU', "<ul><li>\$1</li>\n", $text, 1 );
+                        // Wrap subsequent list items in 'li' tags.
+                        $text = preg_replace( '~^' . preg_quote( $li ) . '(.+)$~mU', "<li>\$1</li>\n", $text ); 
+                        $text = trim( $text );
+
+                        // Close the list if it hasn't been closed before start of next hash parameter.
+                        //$text = preg_replace( '~(</li>)(\s+</li>)~smU', '$1</ul>$2', $text );
+                        $text = preg_replace( '~(</li>)(\s*</li>)~smU', '$1</ul>$2', $text );
+
+                        // Closethe list if it hasn't been closed and it's the end of the description.
+                        if ( '</li>' === substr( trim( $text ), -5 ) ) {
+                                $text .= '</ul>';
+                        }
+                }
+
+                return $text;
+        }
+
+        /**
          * Formats the output of params defined using hash notation.
          *

sites/trunk/wordpress.org/public_html/wp-content/themes/pub/wporg-developer/scss/main.scss

@@ -1088 +1088 @@
                                         font-style: italic;
                                 }
+
+                                ul {
+                                        margin-left: 25px;
+                                        margin-left: 2.5rem;
+                                }
                         }
                         .param-hash {
                                 margin-left: 1.2em;
                                 margin-bottom: 0.5em;
-                                li {
+                                > li {
                                         margin-top: 1em;
+                                }
+                                li li {
+                                        list-style-type: circle;
+                                }
+                                .param-hash > li {
+                                        list-style-type: disc;
                                 }
                         }

sites/trunk/wordpress.org/public_html/wp-content/themes/pub/wporg-developer/stylesheets/main.css

@@ -1477 +1477 @@
 }
 
+.devhub-wrap .wp-parser-class .parameters dd ul, .devhub-wrap .wp-parser-function .parameters dd ul, .devhub-wrap .wp-parser-hook .parameters dd ul, .devhub-wrap .wp-parser-method .parameters dd ul {
+  margin-left: 25px;
+  margin-left: 2.5rem;
+}
+
 .devhub-wrap .wp-parser-class .parameters .param-hash, .devhub-wrap .wp-parser-function .parameters .param-hash, .devhub-wrap .wp-parser-hook .parameters .param-hash, .devhub-wrap .wp-parser-method .parameters .param-hash {
   margin-left: 1.2em;
@@ -1482 +1487 @@
 }
 
-.devhub-wrap .wp-parser-class .parameters .param-hash li, .devhub-wrap .wp-parser-function .parameters .param-hash li, .devhub-wrap .wp-parser-hook .parameters .param-hash li, .devhub-wrap .wp-parser-method .parameters .param-hash li {
+.devhub-wrap .wp-parser-class .parameters .param-hash > li, .devhub-wrap .wp-parser-function .parameters .param-hash > li, .devhub-wrap .wp-parser-hook .parameters .param-hash > li, .devhub-wrap .wp-parser-method .parameters .param-hash > li {
   margin-top: 1em;
+}
+
+.devhub-wrap .wp-parser-class .parameters .param-hash li li, .devhub-wrap .wp-parser-function .parameters .param-hash li li, .devhub-wrap .wp-parser-hook .parameters .param-hash li li, .devhub-wrap .wp-parser-method .parameters .param-hash li li {
+  list-style-type: circle;
+}
+
+.devhub-wrap .wp-parser-class .parameters .param-hash .param-hash > li, .devhub-wrap .wp-parser-function .parameters .param-hash .param-hash > li, .devhub-wrap .wp-parser-hook .parameters .param-hash .param-hash > li, .devhub-wrap .wp-parser-method .parameters .param-hash .param-hash > li {
+  list-style-type: disc;
 }