[elpa] externals/dash 3fa27c4 295/316: Make README's def-example-group more like manual's

[ELPA Syncer]

branch: externals/dash
commit 3fa27c484c3d644c0f571524a9e2934bc7178c6b
Author: Basil L. Contovounesios <contovob@tcd.ie>
Commit: Basil L. Contovounesios <contovob@tcd.ie>

    Make README's def-example-group more like manual's
    
    * dev/examples-to-docs.el (def-example-group): Use text properties
    to mark group headings.
    (function-to-md, function-summary): Simplify accordingly.  Remove
    gratuitous newlines.
    
    * README.md: Regenerate.
---
 README.md               | 42 ------------------------------------------
 dev/examples-to-docs.el | 25 ++++++++++++++-----------
 2 files changed, 14 insertions(+), 53 deletions(-)

diff --git a/README.md b/README.md
index 2b87b36..336b587 100644
--- a/README.md
+++ b/README.md
@@ -106,7 +106,6 @@ This demonstrates the utility of both versions.
 
 ### Maps
 
-
 Functions in this category take a transforming function, which
 is then applied sequentially to each or selected elements of the
 input list.  The results are collected in order and returned as a
@@ -125,7 +124,6 @@ new list.
 
 ### Sublist selection
 
-
 Functions returning a sublist of the original list.
 
 * [`-filter`](#-filter-pred-list) `(pred list)`
@@ -147,7 +145,6 @@ Functions returning a sublist of the original list.
 
 ### List to list
 
-
 Functions returning a modified copy of the input list.
 
 * [`-keep`](#-keep-fn-list) `(fn list)`
@@ -165,7 +162,6 @@ Functions returning a modified copy of the input list.
 
 ### Reductions
 
-
 Functions reducing lists to a single value (which may also be a list).
 
 * [`-reduce-from`](#-reduce-from-fn-init-list) `(fn init list)`
@@ -192,7 +188,6 @@ Functions reducing lists to a single value (which may also 
be a list).
 
 ### Unfolding
 
-
 Operations dual to reductions, building lists from a seed
 value rather than consuming a list to produce a single value.
 
@@ -214,7 +209,6 @@ value rather than consuming a list to produce a single 
value.
 
 ### Partitioning
 
-
 Functions partitioning the input list into a list of lists.
 
 * [`-split-at`](#-split-at-n-list) `(n list)`
@@ -236,7 +230,6 @@ Functions partitioning the input list into a list of lists.
 
 ### Indexing
 
-
 Return indices of elements based on predicates, sort elements by indices etc.
 
 * [`-elem-index`](#-elem-index-elem-list) `(elem list)`
@@ -249,7 +242,6 @@ Return indices of elements based on predicates, sort 
elements by indices etc.
 
 ### Set operations
 
-
 Operations pretending lists are sets.
 
 * [`-union`](#-union-list-list2) `(list list2)`
@@ -261,7 +253,6 @@ Operations pretending lists are sets.
 
 ### Other list operations
 
-
 Other list functions not fit to be classified elsewhere.
 
 * [`-rotate`](#-rotate-n-list) `(n list)`
@@ -296,7 +287,6 @@ Other list functions not fit to be classified elsewhere.
 
 ### Tree operations
 
-
 Functions pretending lists are trees.
 
 * [`-tree-seq`](#-tree-seq-branch-children-tree) `(branch children tree)`
@@ -321,7 +311,6 @@ Functions pretending lists are trees.
 
 ### Binding
 
-
 Convenient versions of `let` and `let*` constructs combined with flow control.
 
 * [`-when-let`](#-when-let-var-val-rest-body) `((var val) &rest body)`
@@ -335,7 +324,6 @@ Convenient versions of `let` and `let*` constructs combined 
with flow control.
 
 ### Side effects
 
-
 Functions iterating over lists for side effect only.
 
 * [`-each`](#-each-list-fn) `(list fn)`
@@ -352,7 +340,6 @@ Functions iterating over lists for side effect only.
 
 ### Function combinators
 
-
 These combinators require Emacs 24 for its lexical scope. So they are offered 
in a separate package: `dash-functional`.
 
 * [`-partial`](#-partial-fn-rest-args) `(fn &rest args)`
@@ -371,10 +358,8 @@ These combinators require Emacs 24 for its lexical scope. 
So they are offered in
 * [`-fixfn`](#-fixfn-fn-optional-equal-test-halt-test) `(fn &optional 
equal-test halt-test)`
 * [`-prodfn`](#-prodfn-rest-fns) `(&rest fns)`
 
-
 ## Maps
 
-
 Functions in this category take a transforming function, which
 is then applied sequentially to each or selected elements of the
 input list.  The results are collected in order and returned as a
@@ -507,10 +492,8 @@ Create a shallow copy of `list`.
 (let ((a '(1 2 3))) (eq a (-copy a))) ;; => nil
 ```
 
-
 ## Sublist selection
 
-
 Functions returning a sublist of the original list.
 
 #### -filter `(pred list)`
@@ -737,10 +720,8 @@ See also: 
[`-select-columns`](#-select-columns-columns-table), [`-select-by-indi
 (-select-column 1 '((1 2 3) (a b c) (:a :b :c))) ;; => '(2 b :b)
 ```
 
-
 ## List to list
 
-
 Functions returning a modified copy of the input list.
 
 #### -keep `(fn list)`
@@ -901,10 +882,8 @@ See also: [`-remove-at`](#-remove-at-n-list), 
[`-remove`](#-remove-pred-list)
 (-remove-at-indices '(0 5) '("0" "1" "2" "3" "4" "5")) ;; => '("1" "2" "3" "4")
 ```
 
-
 ## Reductions
 
-
 Functions reducing lists to a single value (which may also be a list).
 
 #### -reduce-from `(fn init list)`
@@ -1189,10 +1168,8 @@ comparing them.
 (--max-by (> (length it) (length other)) '((1 2 3) (2) (3 2))) ;; => '(1 2 3)
 ```
 
-
 ## Unfolding
 
-
 Operations dual to reductions, building lists from a seed
 value rather than consuming a list to produce a single value.
 
@@ -1230,7 +1207,6 @@ the new seed.
 (--unfold (when it (cons it (butlast it))) '(1 2 3 4)) ;; => '((1 2 3 4) (1 2 
3) (1 2) (1))
 ```
 
-
 ## Predicates
 
 #### -any? `(pred list)`
@@ -1361,10 +1337,8 @@ Alias: `-cons-pair-p`.
 (-cons-pair? '(1)) ;; => nil
 ```
 
-
 ## Partitioning
 
-
 Functions partitioning the input list into a list of lists.
 
 #### -split-at `(n list)`
@@ -1555,10 +1529,8 @@ elements of `list`.  Keys are compared by `equal`.
 (--group-by (car (split-string it "/")) '("a/b" "c/d" "a/e")) ;; => '(("a" 
"a/b" "a/e") ("c" "c/d"))
 ```
 
-
 ## Indexing
 
-
 Return indices of elements based on predicates, sort elements by indices etc.
 
 #### -elem-index `(elem list)`
@@ -1645,10 +1617,8 @@ permutation to `list` sorts it in descending order.
 (let ((l '(3 1 4 2 1 3 3))) (-select-by-indices (-grade-down #'< l) l)) ;; => 
'(4 3 3 3 2 1 1)
 ```
 
-
 ## Set operations
 
-
 Operations pretending lists are sets.
 
 #### -union `(list list2)`
@@ -1720,10 +1690,8 @@ Alias: `-uniq`
 (-distinct '(t t t)) ;; => '(t)
 ```
 
-
 ## Other list operations
 
-
 Other list functions not fit to be classified elsewhere.
 
 #### -rotate `(n list)`
@@ -2116,10 +2084,8 @@ Compute the (least) fixpoint of `fn` with initial input 
`list`.
 (let ((l '((starwars scifi) (jedi starwars warrior)))) (--fix (-uniq (--mapcat 
(cons it (cdr (assq it l))) it)) '(jedi book))) ;; => '(jedi starwars warrior 
scifi book)
 ```
 
-
 ## Tree operations
 
-
 Functions pretending lists are trees.
 
 #### -tree-seq `(branch children tree)`
@@ -2243,7 +2209,6 @@ structure such as plist or alist.
 (let* ((a '(1 2 3)) (b (-clone a))) (nreverse a) b) ;; => '(1 2 3)
 ```
 
-
 ## Threading macros
 
 #### -> `(x &optional form &rest more)`
@@ -2347,10 +2312,8 @@ which `forms` may have modified by side effect.
 (gethash 'k (--doto (make-hash-table) (puthash 'k 'v it))) ;; => 'v
 ```
 
-
 ## Binding
 
-
 Convenient versions of `let` and `let*` constructs combined with flow control.
 
 #### -when-let `((var val) &rest body)`
@@ -2646,10 +2609,8 @@ multiple assignments it does not cause unexpected side 
effects.
 (let (c) (-setq (&plist :c c) (list :c "c")) c) ;; => "c"
 ```
 
-
 ## Side effects
 
-
 Functions iterating over lists for side effect only.
 
 #### -each `(list fn)`
@@ -2732,7 +2693,6 @@ This function's anaphoric counterpart is `--dotimes`.
 (let (s) (--dotimes 5 (push it s)) s) ;; => '(4 3 2 1 0)
 ```
 
-
 ## Destructive operations
 
 #### !cons `(car cdr)`
@@ -2753,10 +2713,8 @@ Destructive: Set `list` to the cdr of `list`.
 (let ((l '(3 5))) (!cdr l) l) ;; => '(5)
 ```
 
-
 ## Function combinators
 
-
 These combinators require Emacs 24 for its lexical scope. So they are offered 
in a separate package: `dash-functional`.
 
 #### -partial `(fn &rest args)`
diff --git a/dev/examples-to-docs.el b/dev/examples-to-docs.el
index 9012470..5bb0877 100644
--- a/dev/examples-to-docs.el
+++ b/dev/examples-to-docs.el
@@ -79,7 +79,7 @@ Based on `describe-function-1'."
 
 (defmacro def-example-group (group desc &rest examples)
   `(progn
-     (push ,(concat "### " group) functions)
+     (push ,(propertize group 'dash-group t) functions)
      (when ,desc
        (push ,desc functions))
      ,@examples))
@@ -136,15 +136,16 @@ Based on `describe-function-1'."
       (buffer-string))))
 
 (defun function-to-md (function)
-  (if (stringp function)
-      (concat "\n" (replace-regexp-in-string (rx bos "### ") "## " function)
-              "\n")
-    (-let [(command-name signature docstring examples) function]
-      (format "#### %s `%s`\n\n%s\n\n```el\n%s\n```\n"
-              command-name
-              signature
-              (dash--format-docstring docstring)
-              (mapconcat #'example-to-string (-take 3 examples) "\n")))))
+  (pcase function
+    (`(,command-name ,signature ,docstring ,examples)
+     (format "#### %s `%s`\n\n%s\n\n```el\n%s\n```\n"
+             command-name
+             signature
+             (dash--format-docstring docstring)
+             (mapconcat #'example-to-string (-take 3 examples) "\n")))
+    ((pred (get-text-property 0 'dash-group))
+     (concat "## " function "\n"))
+    (_ (concat function "\n"))))
 
 (defun dash--github-link (fn signature)
   (--> (string-remove-prefix "!" (format "%s%s" fn signature))
@@ -155,7 +156,9 @@ Based on `describe-function-1'."
   (pcase function
     (`(,fn ,signature . ,_)
      (format "* %s `%s`" (dash--github-link fn signature) signature))
-    (_ (concat "\n" function "\n"))))
+    ((pred (get-text-property 0 'dash-group))
+     (concat "\n### " function "\n"))
+    (_ (concat function "\n"))))
 
 (defun dash--replace-all (old new)
   "Replace occurrences of OLD with NEW in current buffer."