update the article on shuffle words to hide away the more troublesome ones

core/kernel/kernel-docs.factor

@@ -821,10 +821,26 @@ HELP: assert=
 { $values { "a" object } { "b" object } }
 { $description "Throws an " { $link assert } " error if " { $snippet "a" } " does not equal " { $snippet "b" } "." } ;
 
-ARTICLE: "shuffle-words" "Shuffle words"
+ARTICLE: "shuffle-words-complex" "Complex shuffle words"
-"Shuffle words rearrange items at the top of the data stack. They control the flow of data between words that perform actions."
+"These shuffle words tend to make code difficult to read and reason about. Code that uses them should almost always be rewritten in terms of the " { $link "dataflow-combinators" } "."
 $nl
-"The " { $link "cleave-combinators" } ", " { $link "spread-combinators" } " and " { $link "apply-combinators" } " are closely related to shuffle words and should be used instead where possible because they can result in clearer code; also, see the advice in " { $link "cookbook-philosophy" } "."
+"Duplicating stack elements deep in the stack:"
+{ $subsections
+    dupd
+    tuck
+}
+"Permuting stack elements deep in the stack:"
+{ $subsections
+    swapd
+    rot
+    -rot
+    spin
+    roll
+    -roll
+} ;
+
+ARTICLE: "shuffle-words" "Shuffle words"
+"Shuffle words rearrange items at the top of the data stack. They provide simple data flow control between words. More complex data flow control is available through the " { $link "dataflow-combinators" } "."
 $nl
 "Removing stack elements:"
 { $subsections
@@ -839,21 +855,17 @@ $nl
     dup
     2dup
     3dup
-    dupd
     over
     2over
     pick
-    tuck
 }
 "Permuting stack elements:"
 { $subsections
     swap
-    swapd
+}
-    rot
+"There are additional, more complex stack shuffling words whose use is not recommended."
-    -rot
+{ $subsections
-    spin
+    "shuffle-words-complex"
-    roll
-    -roll
 } ;
 
 ARTICLE: "equality" "Equality"