Improve documentation for "Finitely presented groups"

docs/src/Groups/fpgroup.md

@@ -5,15 +5,118 @@ DocTestSetup = Oscar.doctestsetup()
 
 # Finitely presented groups
 
+## Introduction
+
+A *finitely presented group* is a group generated by a finite set
+of generators subject to a finite set of relations
+that these generators satisfy.
+
+A finitely presented group arises as a quotient $G$ of a free group $F$
+by the normal subgroup of $F$ that is defined as the normal closure of
+a vector of elements in $F$;
+these elements are called the *defining relators* of $G$,
+see [`relators`](@ref).
+
+Finitely presented groups in Oscar have the type [`FPGroup`](@ref),
+their elements have the type [`FPGroupElem`](@ref).
+
+## Basic Creation
+
+In order to *create* a finitely presented group,
+one first creates a free group (see [`free_group`](@ref)).
+This group is already a finitely presented group,
+it has an empty vector of defining relators.
+
+```jldoctest fpgroupxpl
+julia> F = free_group(2)
+Free group of rank 2
+
+julia> gens(F)
+2-element Vector{FPGroupElem}:
+ f1
+ f2
+
+julia> f1, f2 = gens(F);
+```
+
+(See [`@free_group`](@ref) for ways to automatically assign variables
+corresponding to the generators of a free group.)
+
+If one wants a finitely presented group with nontrivial defining relators
+then one chooses these defining relators, and then calls
+[`quo(G::T, elements::Vector{S}) where T <: GAPGroup where S <: GAPGroupElem`](@ref).
+
+```jldoctest fpgroupxpl
+julia> rels = [f1^2, f2^3, f1*f2*f1*f2^2]
+3-element Vector{FPGroupElem}:
+ f1^2
+ f2^3
+ (f1*f2)^2*f2
+
+julia> G, epi = quo(F, rels)
+(Finitely presented group, Hom: F -> G)
+
+julia> gens(G)
+2-element Vector{FPGroupElem}:
+ f1
+ f2
+
+julia> order(G)
+6
+```
+
+Note that the generators of the free group `F` and its quotient group `G`
+(and the way how they are printed) correspond to each other,
+but one cannot compare or multiply an element of `F` with an element of `G`;
+use the epimorphism returned by `quo` to map elements from `F` to `G`.
+
+```jldoctest fpgroupxpl
+julia> map(epi, gens(F)) == gens(G)
+true
+```
+
+Subgroups of finitely presented groups in Oscar have the type
+[`SubFPGroup`](@ref),
+their elements have the type [`SubFPGroupElem`](@ref).
+
+```jldoctest fpgroupxpl
+julia> S, emb = sylow_subgroup(G, 2)
+(Sub-finitely presented group of order 2, Hom: S -> G)
+
+julia> gens(S)
+1-element Vector{SubFPGroupElem}:
+ f1
+```
+
+Note that although finitely presented groups arise naturally
+in many situations,
+it is very often computationally much more efficient to work
+with groups in other representations
+(even the regular permutation representation).
+
+```jldoctest fpgroupxpl
+julia> iso = isomorphism(PermGroup, G)
+Group homomorphism
+  from finitely presented group of order 6
+  to permutation group of degree 5 and order 6
+```
+
+## Functions for (subgroups of) finitely presented groups and their elements
+
 ```@docs
-FPGroup
-FPGroupElem
-SubFPGroup
-SubFPGroupElem
 free_group
 @free_group
 full_group(G::Union{SubFPGroup, SubPcGroup})
 relators(G::FPGroup)
 length(g::Union{FPGroupElem, SubFPGroupElem})
 map_word(g::Union{FPGroupElem, SubFPGroupElem}, genimgs::Vector; genimgs_inv::Vector = Vector(undef, length(genimgs)), init = nothing)
 ```
+
+## Technicalities
+
+```@docs
+FPGroup
+FPGroupElem
+SubFPGroup
+SubFPGroupElem
+```