shun ugly shuffle words in the docs

basis/help/markup/markup.factor

@@ -1,9 +1,9 @@
 ! Copyright (C) 2005, 2009 Slava Pestov.
 ! See http://factorcode.org/license.txt for BSD license.
 USING: accessors arrays assocs classes colors colors.constants
-combinators definitions definitions.icons effects fry generic
+combinators combinators.smart definitions definitions.icons effects
-hashtables help.stylesheet help.topics io io.styles kernel make
+fry generic hashtables help.stylesheet help.topics io io.styles
-math namespaces parser present prettyprint
+kernel make math namespaces parser present prettyprint
 prettyprint.stylesheet quotations see sequences sets slots
 sorting splitting strings vectors vocabs vocabs.loader words
 words.symbol ;
@@ -398,7 +398,12 @@ M: f ($instance)
 
 : $shuffle ( element -- )
     drop
-    "Shuffle word. Re-arranges the stack according to the stack effect pattern." $description ;
+    "Shuffle word. Rearranges the top of the datastack as indicated in the stack effect pattern." $description ;
+
+: $complex-shuffle ( element -- )
+    drop
+    "Shuffle word. Rearranges the top of the datastack as indicated in the stack effect pattern." $description
+    { "The data flow represented by this shuffle word can be more clearly expressed using " { $link "locals" } "." } $deprecated ;
 
 : $low-level-note ( children -- )
     drop

core/kernel/kernel-docs.factor

@@ -14,20 +14,21 @@ HELP: 3drop ( x y z -- )             $shuffle ;
 HELP: dup   ( x -- x x )             $shuffle ;
 HELP: 2dup  ( x y -- x y x y )       $shuffle ;
 HELP: 3dup  ( x y z -- x y z x y z ) $shuffle ;
-HELP: rot   ( x y z -- y z x )       $shuffle ;
-HELP: -rot  ( x y z -- z x y )       $shuffle ;
-HELP: dupd  ( x y -- x x y )         $shuffle ;
-HELP: swapd ( x y z -- y x z )       $shuffle ;
 HELP: nip   ( x y -- y )             $shuffle ;
 HELP: 2nip  ( x y z -- z )           $shuffle ;
-HELP: tuck  ( x y -- y x y )         $shuffle ;
 HELP: over  ( x y -- x y x )         $shuffle ;
 HELP: 2over                          $shuffle ;
 HELP: pick  ( x y z -- x y z x )     $shuffle ;
 HELP: swap  ( x y -- y x )           $shuffle ;
-HELP: spin                           $shuffle ;
+
-HELP: roll                           $shuffle ;
+HELP: spin                     $complex-shuffle ;
-HELP: -roll                          $shuffle ;
+HELP: rot   ( x y z -- y z x ) $complex-shuffle ;
+HELP: -rot  ( x y z -- z x y ) $complex-shuffle ;
+HELP: dupd  ( x y -- x x y )   $complex-shuffle ;
+HELP: swapd ( x y z -- y x z ) $complex-shuffle ;
+HELP: tuck  ( x y -- y x y )   $complex-shuffle ;
+HELP: roll  $complex-shuffle ;
+HELP: -roll $complex-shuffle ;
 
 HELP: datastack ( -- ds )
 { $values { "ds" array } }
@@ -822,7 +823,7 @@ HELP: assert=
 { $description "Throws an " { $link assert } " error if " { $snippet "a" } " does not equal " { $snippet "b" } "." } ;
 
 ARTICLE: "shuffle-words-complex" "Complex shuffle words"
-"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" } "."
+"These shuffle words tend to make code difficult to read and to reason about. Code that uses them should almost always be rewritten using " { $link "locals" } " or " { $link "dataflow-combinators" } "."
 $nl
 "Duplicating stack elements deep in the stack:"
 { $subsections
@@ -834,13 +835,13 @@ $nl
     swapd
     rot
     -rot
-    spin
     roll
     -roll
+    spin
 } ;
 
 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" } "."
+"Shuffle words rearrange items at the top of the data stack as indicated by their stack effects. They provide simple data flow control between words. More complex data flow control is available with the " { $link "dataflow-combinators" } " and with " { $link "locals" } "."
 $nl
 "Removing stack elements:"
 { $subsections