ENHANCE: Added manual to `LowIndexSubgroups'.

as requested in gap-system#2131

Also added `LowLayerSubgroups` and minor rephrasing.

Also redid part of gap-system#683, as for some reason (probably my stupidity)
part of gap-system#683 had fallen out of master. Added it again.

doc/ref/groups.xml

@@ -449,8 +449,9 @@ the series without destroying the properties of the series.
 <#Include Label="IsConjugacyClassSubgroupsRep">
 <#Include Label="ConjugacyClassesSubgroups">
 <#Include Label="ConjugacyClassesMaximalSubgroups">
-<#Include Label="AllSubgroups">
 <#Include Label="MaximalSubgroupClassReps">
+<#Include Label="LowIndexSubgroups">
+<#Include Label="AllSubgroups">
 <#Include Label="MaximalSubgroups">
 <#Include Label="NormalSubgroups">
 <#Include Label="MaximalNormalSubgroups">

lib/grp.gd

@@ -4495,12 +4495,12 @@ DeclareGlobalFunction("GroupEnumeratorByClosure");
 ##
 ##  <#GAPDoc Label="LowIndexSubgroups">
 ##  <ManSection>
-##  <Oper Name="LowIndexSubgroups"
-##   Arg='G, index'/>
 ##  <Oper Name="LowIndexSubgroups" Arg='G, index'/>
+##  <Oper Name="LowLayerSubgroups" Arg='G, layer'/>
 ##
 ##  <Description>
-##  These operations computes representatives of the conjugacy classes of
+##  The operation <C>LowIndexSubgroups</C> computes representatives of the
+##  conjugacy classes of
 ##  subgroups of the group <A>G</A> that 
 ##  index less than or equal to
 ##  <A>index</A>.
@@ -4509,13 +4509,15 @@ DeclareGlobalFunction("GroupEnumeratorByClosure");
 ##  <C>LowIndexSubgroupsFpGroup</C>. In other cases, it uses repeated
 ##  calculation of maximal subgroups.
 ##  <P/>
+##  The operation <C>LowLayerSubgroups</C> works similar but does not bound
+##  the index, but instead considers up to <A>layer</A>-th maximal
+##  subgroups.
 ##  <Example><![CDATA[
 ##  gap> g:=TransitiveGroup(18,950);;
 ##  gap> l:=LowIndexSubgroups(g,20);;Collected(List(l,x->Index(g,x)));
 ##  [ [ 1, 1 ], [ 2, 1 ], [ 5, 1 ], [ 6, 1 ], [ 10, 2 ], [ 12, 3 ], [ 15, 1 ], 
 ##    [ 16, 2 ], [ 18, 1 ], [ 20, 9 ] ]
 ##  ]]></Example>
-##  <P/>
 ##  </Description>
 ##  </ManSection>
 ##  <#/GAPDoc>

lib/grplatt.gi

@@ -3053,6 +3053,23 @@ local recog,m,len;
   return m;
 end);
 
+InstallMethod(LowIndexSubgroups,"finite groups, using iterated maximals",
+  true,[IsGroup and IsFinite,IsPosInt],0,
+function(G,n)
+local m,all,m2;
+  m:=[G];
+  all:=[G];
+  while Length(m)>0 do
+    m2:=Concatenation(List(m,MaximalSubgroupClassReps));
+    m2:=Unique(Filtered(m2,x->Index(G,x)<=n));
+    m2:=List(SubgroupsOrbitsAndNormalizers(G,m2,false),x->x.representative);
+    m2:=Filtered(m2,x->ForAll(all,y->RepresentativeAction(G,x,y)=fail));
+    Append(all,m2);
+    m:=Filtered(m2,x->Index(G,x)<=n/2); # otherwise subgroups will have too large index
+  od;
+  return all;
+end);
+
 #############################################################################
 ##
 #F  LowLayerSubgroups( [<act>,] <G>, <lim> [,<cond> [,<dosub>]] )