Random source are documented in "Integers" chapter; move them? (to a new chapter)?

[fingolfin]

Right now, Random source are documented in section 14.17 of the "Integers" chapter. I find that quite counterintuitive and really weird.

So perhaps we should move them to a more appropriate location? Perhaps together with section 30.7 "Random Elements"

But where? Perhaps to a new chapter? But are we willing to insert a new chapter, as that would renumber all following chapters, and break hyperlinks of package manuals... ??

And if we move it to a new chapter, would it be a chapter title "Random", or rather a chapter "Miscellaneous", and we'd move some other things there which are weirdly placed right now (IIRC there are some, but I don't know any from the top of my head).

[ChrisJefferson]

It is weird. I wonder also if we should document every specialisation of Random, or just the general method.

[fingolfin]

@ChrisJefferson See also #116

[fingolfin]

At the very least, it would be good to merge the documentation for Random( listorcoll ) and Random( rs, list ) (into an entry saying Random( [rs, ]listorcoll ), I guess?) and similar for Random( from, to ) and Random( rs, low, high ). Right now, I think neither refers to the other.

Moreover, some of them are defined and documented in coll.gd, the others in random.gd. When merging their documentation, I'd also move their declarations into the same file (preferable random.gd?) and move them together.

And while we are at it, random source arguments should ideally also be added to PseudoRandom and RandomList. Note that the latter is useful as an alternative to Random(list) because it avoids the method selection overhead (which is very heavy for lists, as their types has to be recomputed each time).