Improve documentation for "Finitely presented groups" and other types of groups

[thofma]

I was trying to steer someone to use Oscar to create a finitely presented group, but I had trouble pointing the person to some useful information in the documentation:

• The documentation on finitely presented groups could benefit from having a "Here is an example of how to construct a finitely presented group", which should be near the beginning.
• The longish (repetitive) texts for FPGroup, FPGroupElem, SubFPGroup and SubFPGroupElem should in my opinion not be at the top. Maybe the could be replaced by a sentence of the form "The type for f.p. groups is ... and the elements have type ..."?

Just some thoughts. I am also happy to help with this if we agree on these points or something similar.

CC: @fingolfin @ThomasBreuer

[ThomasBreuer]

Shall we perhaps take the structure of the manual section on Abelian Groups as a model for the other kinds of groups,
that is, start with an "Introduction" that states some sentences, then "Basic Creation" shows the relevant constructors with the examples in question, and then sections about other functionality follows?

Should docstrings for the types better not appear at all in the manual, and be replaced by textual descriptions (perhaps in the "Introduction", perhaps in a "Technicalities" section at the end)?

This issue is only about f.p. groups but I think the same holds also for pc groups, matrix groups, likely also for perm. groups.

[thofma]

Shall we perhaps take the structure of the manual section on Abelian Groups as a model for the other kinds of groups, that is, start with an "Introduction" that states some sentences, then "Basic Creation" shows the relevant constructors with the examples in question, and then sections about other functionality follows?

Yes, I think this would be a good idea. It is also similar to how GAP and Magma do it. They both have some introductory blurb at the beginning. Which is followed by some explanations on how to construct these objects.

Should docstrings for the types better not appear at all in the manual, and be replaced by textual descriptions (perhaps in the "Introduction", perhaps in a "Technicalities" section at the end)?

I think we need to mention the types in the introductory blurb, since they pop up in the signatures that follow.

Pushing the docstrings of the types themselves into some "Technicalities" section is in my opinion a good idea.

[ThomasBreuer]

Thanks.
I am going to propose a change in this direction for the f.p. groups section. Once we agree how this should look like, the other sections can be changed analogously.