Merge documentation entries for 'Random'

[fingolfin]

My students are having quite some trouble finding the Random( from, to ) variant of Random they need for some course problems. This excerpt of the ref manual shows why:

Random, for a list 14.7-2
Random, for a list or collection 30.7-1
Random, for a range of integers 14.7-2
Random, for integers 14.2-12
Random, for lower and upper bound 30.7-1
Random, for rationals 17.2-7
random element, of a list or collection 30.7-1

I.e. they need to look at 14.2, 14.7, 17.2 and 30.7, and then also understand each.

I propose we unify these entries in a single entry, unless somebody has a suggestion as to why it would be useful to keep those separate entries (which also spam the built-in GAP help function with distracting data).

[ChrisJefferson]

I agree, good plan.

[olexandr-konovalov]

On the other hand, Random is an operation and various methods for it may be documented in various sections of the manual, so that their documentation will be brought closer to the documentation for objects used as arguments of Random. So I am not so sure that we need to unify this, moreover, in GAP 4.7.7 installation entering ?Random results in 106 entries starting from the string Random, including package manuals, so the effect of this change might not be visible.

[markuspf]

So, what we need is a well-visible first point of call about Random that then links to details about Random for different objects?

I am a bit afraid that this might turn into a refactoring project for the documentation...

[fingolfin]

Yes, this kind of a "refactoring problem" for the manual.

We badly need to do that anyway. Many questions in the GAP forum and elsewhere arise because people don't find things in the manual. In fact, I myself often don't find things. :-(

[fingolfin]

@alex-konovalov I'd argue that documenting different methods for Random in different places is a bad idea to start with. User's do not care about methods -- they just know there is a function Random, and want to use it. Only advanced user's even understand the distinction between a plain function, and an operation with different methods...

Yes, packages can define additional information in their manuals, but that is not an excuse to keep the main manual in a bad shape.

[frankluebeck]

I don't agree that the documentation about Random is in a very bad state. The main point is that a user asking ?Random in GAPs help system did not get the most relevant section as first match. This (and also a mistake in the documentation of Random with a random source as first argument) is fixed in the pull request "Better match list for ?Random" (#410).

I have recently changed the programs in GAPDoc which generate the indices in the text and HTML version of a manual. Therefore, with the next version of GAPDoc the index will look like:

Random 30.7-1 
  for a list or collection 30.7-1 
  for integers 14.2-12 
  for lower and upper bound 30.7-1 
  for random source and list 14.7-2 
  for random source and two integers 14.7-2 
  for rationals 17.2-7 

@fingolfin said:

I'd argue that documenting different methods for Random in different places is a bad idea to start with. User's do not care about methods -- they just know there is a function Random, and want to use it. Only advanced user's even understand the distinction between a plain function, and an operation with different methods...

I totally disagree with this view! Just the other way round, it would be good if more methods would be documented (and for example give references to underlying algorithms, or hints about their practical applicability).

[olexandr-konovalov]

@markuspf @fingolfin @frankluebeck shall we close this issue then? Frank's PR #410 had been merged, so it remains only to wait for the next version of GAPDoc announced above.

[dimpase]

I think that docs for Random should at least document the calls in testinstall/intarith.tst
Currently I have trouble finding the docs for Random(mysource, 1, 2^80) (a 3-parameter version, which one, in which of the zillion of entries for ?Radom ?)

As well, RandomSource(...,42) usage there does not match the ?RandomSource output, as the latter says that the 2nd parameter must be a string.