implement an improved random command

Fixes #2642

doc_src/random.txt

@@ -2,31 +2,40 @@
 
 \subsection random-synopsis Synopsis
 \fish{synopsis}
-random [SEED]
+random
+random SEED
+random START END
+random START STEP END
+random choice [ITEMS...]
 \endfish
 
 \subsection random-description Description
 
-`random` outputs a psuedo-random number from 0 to 32767, inclusive.
-Even ignoring the very narrow range of values you should not assume
-this produces truly random values within that range. Do not use the
-value for any cryptographic purposes, and take care to handle collisions:
-the same random number appearing more than once in a given fish instance.
+`RANDOM` generates a pseudo-random integer from a uniform distribution. The
+range (inclusive) is dependent on the arguments passed.
+No arguments indicate a range of [0; 32767].
+If one argument is specified, the internal engine will be seeded with the
+argument for future invocations of `RANDOM` and no output will be produced.
+Two arguments indicate a range of [START; END].
+Three arguments indicate a range of [START; END] with a spacing of STEP
+between possible outputs.
+`RANDOM choice` will select one random item from the succeeding arguments.
 
-If a `SEED` value is provided, it is used to seed the random number
-generator, and no output will be produced. This can be useful for debugging
-purposes, where it can be desirable to get the same random number sequence
-multiple times. If the random number generator is called without first
-seeding it, the current time will be used as the seed.
+Note that seeding the engine will NOT give the same result across different
+systems.
 
+You should not consider `RANDOM` cryptographically secure, or even
+statistically accurate.
 
 \subsection random-example Example
 
-The following code will count down from a random number to 1:
-
+The following code will count down from a random even number between 10 and 20 to 1:
 \fish
-for i in (seq (random) -1 1)
+for i in (seq (random 10 2 20) -1 1)
     echo $i
-    sleep
 end
 \endfish
+And this will open a random picture from any of the subdirectories:
+\fish 
+open (random choice **jpg)
+\endfish