docs: mention FirstOp, LastOp, ForAllOp, etc.

... in the documentation entries for their non-Op counterparts First, Last,
ForAll, etc. and explain that custom methods need to be installed there.

Also explain uniformly that this is to avoid the method selection overhead
penalty for plain list inputs.

lib/coll.gd

@@ -2051,6 +2051,10 @@ DeclareAttribute( "UnderlyingCollection", IsListOrCollection );
 ##  same as <Ref Oper="ShallowCopy"/> (see also 
 ##  <Ref Sect="Duplication of Lists"/>).
 ##  <P/>
+##  Developers who wish to adapt this for custom list or collection types need to
+##  install suitable methods for the operation <C>ListOp</C>.
+##  <Index Key="ListOp"><C>ListOp</C></Index>
+##  <P/>
 ##  <Example><![CDATA[
 ##  gap> List( [1,2,3], i -> i^2 );
 ##  [ 1, 4, 9 ]
@@ -2084,6 +2088,10 @@ DeclareAttribute( "UnderlyingCollection", IsListOrCollection );
 ##  <!-- this is not reasonable since <C>ShallowCopy</C> need not guarantee to return-->
 ##  <!-- a constant time access list-->
 ##  <P/>
+##  Developers who wish to adapt this for custom list or collection types need to
+##  install suitable methods for the operation <C>ListOp</C>.
+##  <Index Key="ListOp"><C>ListOp</C></Index>
+##  <P/>
 ##  <Example><![CDATA[
 ##  gap> l:= List( Group( (1,2,3) ) );
 ##  [ (), (1,3,2), (1,2,3) ]
@@ -2098,8 +2106,8 @@ DeclareAttribute( "UnderlyingCollection", IsListOrCollection );
 ##  </ManSection>
 ##  <#/GAPDoc>
 ##
+##  We catch internal lists by a function to avoid method selection:
 DeclareGlobalFunction( "List" );
-
 DeclareOperation( "ListOp", [ IsListOrCollection ] );
 DeclareOperation( "ListOp", [ IsListOrCollection, IsFunction ] );
 
@@ -2453,6 +2461,10 @@ DeclareGlobalFunction( "Elements" );
 ##  This is useful for example if the first argument is empty and a different
 ##  zero than <C>0</C> is desired, in which case <A>init</A> is returned.
 ##  <P/>
+##  Developers who wish to adapt this for custom list or collection types need to
+##  install suitable methods for the operation <C>SumOp</C>.
+##  <Index Key="SumOp"><C>SumOp</C></Index>
+##  <P/>
 ##  <Example><![CDATA[
 ##  gap> Sum( [ 2, 3, 5, 7, 11, 13, 17, 19 ] );
 ##  77
@@ -2467,28 +2479,8 @@ DeclareGlobalFunction( "Elements" );
 ##  </ManSection>
 ##  <#/GAPDoc>
 ##
+##  We catch internal lists by a function to avoid method selection:
 DeclareGlobalFunction( "Sum" );
-
-
-#############################################################################
-##
-#O  SumOp( <C> )
-#O  SumOp( <C>, <func> )
-#O  SumOp( <C>, <init> )
-#O  SumOp( <C>, <func>, <init> )
-##
-##  <ManSection>
-##  <Oper Name="SumOp" Arg='C'/>
-##  <Oper Name="SumOp" Arg='C, func'/>
-##  <Oper Name="SumOp" Arg='C, init'/>
-##  <Oper Name="SumOp" Arg='C, func, init'/>
-##
-##  <Description>
-##  <C>SumOp</C> is the operation called by <C>Sum</C>
-##  if <A>C</A> is not an internal list.
-##  </Description>
-##  </ManSection>
-##
 DeclareOperation( "SumOp", [ IsListOrCollection ] );
 
 
@@ -2531,6 +2523,10 @@ DeclareOperation( "SumOp", [ IsListOrCollection ] );
 ##  This is useful for example if the first argument is empty and a different
 ##  identity than <C>1</C> is desired, in which case <A>init</A> is returned.
 ##  <P/>
+##  Developers who wish to adapt this for custom list or collection types need to
+##  install suitable methods for the operation <C>ProductOp</C>.
+##  <Index Key="ProductOp"><C>ProductOp</C></Index>
+##  <P/>
 ##  <Example><![CDATA[
 ##  gap> Product( [ 2, 3, 5, 7, 11, 13, 17, 19 ] );
 ##  9699690
@@ -2545,28 +2541,8 @@ DeclareOperation( "SumOp", [ IsListOrCollection ] );
 ##  </ManSection>
 ##  <#/GAPDoc>
 ##
+##  We catch internal lists by a function to avoid method selection:
 DeclareGlobalFunction( "Product" );
-
-
-#############################################################################
-##
-#O  ProductOp( <C> )
-#O  ProductOp( <C>, <func> )
-#O  ProductOp( <C>, <init> )
-#O  ProductOp( <C>, <func>, <init> )
-##
-##  <ManSection>
-##  <Oper Name="ProductOp" Arg='C'/>
-##  <Oper Name="ProductOp" Arg='C, func'/>
-##  <Oper Name="ProductOp" Arg='C, init'/>
-##  <Oper Name="ProductOp" Arg='C, func, init'/>
-##
-##  <Description>
-##  <C>ProductOp</C> is the operation called by <C>Product</C>
-##  if <A>C</A> is not an internal list.
-##  </Description>
-##  </ManSection>
-##
 DeclareOperation( "ProductOp", [ IsListOrCollection ] );
 
 
@@ -2604,6 +2580,10 @@ DeclareOperation( "ProductOp", [ IsListOrCollection ] );
 ##  (see&nbsp;<Ref Sect="List Assignment"/>) can be used to extract
 ##  elements of a list according to indices given in another list.
 ##  <P/>
+##  Developers who wish to adapt this for custom list or collection types need to
+##  install suitable methods for the operation <C>FilteredOp</C>.
+##  <Index Key="FilteredOp"><C>FilteredOp</C></Index>
+##  <P/>
 ##  <Example><![CDATA[
 ##  gap> Filtered( [1..20], IsPrime );
 ##  [ 2, 3, 5, 7, 11, 13, 17, 19 ]
@@ -2619,22 +2599,8 @@ DeclareOperation( "ProductOp", [ IsListOrCollection ] );
 ##  </ManSection>
 ##  <#/GAPDoc>
 ##
+##  We catch internal lists by a function to avoid method selection:
 DeclareGlobalFunction( "Filtered" );
-
-
-#############################################################################
-##
-#O  FilteredOp( <C>, <func> )
-##
-##  <ManSection>
-##  <Oper Name="FilteredOp" Arg='C, func'/>
-##
-##  <Description>
-##  <C>FilteredOp</C> is the operation called by <C>Filtered</C>
-##  if <A>C</A> is not an internal list.
-##  </Description>
-##  </ManSection>
-##
 DeclareOperation( "FilteredOp", [ IsListOrCollection, IsFunction ] );
 
 
@@ -2671,6 +2637,10 @@ DeclareOperation( "FilteredOp", [ IsListOrCollection, IsFunction ] );
 ##  <Ref Func="Filtered"/> allows you to extract the elements of a list
 ##  that have a certain property.
 ##  <P/>
+##  Developers who wish to adapt this for custom list or collection types need to
+##  install suitable methods for the operation <C>NumberOp</C>.
+##  <Index Key="NumberOp"><C>NumberOp</C></Index>
+##  <P/>
 ##  <Example><![CDATA[
 ##  gap> Number( [ 2, 3, 5, 7 ] );
 ##  4
@@ -2690,22 +2660,8 @@ DeclareOperation( "FilteredOp", [ IsListOrCollection, IsFunction ] );
 ##  </ManSection>
 ##  <#/GAPDoc>
 ##
+##  We catch internal lists by a function to avoid method selection:
 DeclareGlobalFunction( "Number" );
-
-
-#############################################################################
-##
-#O  NumberOp( <C>, <func> )
-##
-##  <ManSection>
-##  <Oper Name="NumberOp" Arg='C, func'/>
-##
-##  <Description>
-##  <C>NumberOp</C> is the operation called by <C>Number</C>
-##  if <A>C</A> is not an internal list.
-##  </Description>
-##  </ManSection>
-##
 DeclareOperation( "NumberOp", [ IsListOrCollection, IsFunction ] );
 
 
@@ -2722,6 +2678,10 @@ DeclareOperation( "NumberOp", [ IsListOrCollection, IsFunction ] );
 ##  tests whether the unary function <A>func</A> returns <K>true</K>
 ##  for all elements in the list or collection <A>listorcoll</A>.
 ##  <P/>
+##  Developers who wish to adapt this for custom list or collection types need to
+##  install suitable methods for the operation <C>ForAllOp</C>.
+##  <Index Key="ForAllOp"><C>ForAllOp</C></Index>
+##  <P/>
 ##  <Example><![CDATA[
 ##  gap> ForAll( [1..20], IsPrime );
 ##  false
@@ -2736,22 +2696,8 @@ DeclareOperation( "NumberOp", [ IsListOrCollection, IsFunction ] );
 ##  </ManSection>
 ##  <#/GAPDoc>
 ##
+##  We catch internal lists by a function to avoid method selection:
 DeclareGlobalFunction( "ForAll" );
-
-
-#############################################################################
-##
-#O  ForAllOp( <C>, <func> )
-##
-##  <ManSection>
-##  <Oper Name="ForAllOp" Arg='C, func'/>
-##
-##  <Description>
-##  <C>ForAllOp</C> is the operation called by <C>ForAll</C>
-##  if <A>C</A> is not an internal list.
-##  </Description>
-##  </ManSection>
-##
 DeclareOperation( "ForAllOp", [ IsListOrCollection, IsFunction ] );
 
 
@@ -2768,6 +2714,10 @@ DeclareOperation( "ForAllOp", [ IsListOrCollection, IsFunction ] );
 ##  tests whether the unary function <A>func</A> returns <K>true</K>
 ##  for at least one element in the list or collection <A>listorcoll</A>.
 ##  <P/>
+##  Developers who wish to adapt this for custom list or collection types need to
+##  install suitable methods for the operation <C>ForAnyOp</C>.
+##  <Index Key="ForAnyOp"><C>ForAnyOp</C></Index>
+##  <P/>
 ##  <Example><![CDATA[
 ##  gap> ForAny( [1..20], IsPrime );
 ##  true
@@ -2784,22 +2734,8 @@ DeclareOperation( "ForAllOp", [ IsListOrCollection, IsFunction ] );
 ##  </ManSection>
 ##  <#/GAPDoc>
 ##
+##  We catch internal lists by a function to avoid method selection:
 DeclareGlobalFunction( "ForAny" );
-
-
-#############################################################################
-##
-#O  ForAnyOp( <C>, <func> )
-##
-##  <ManSection>
-##  <Oper Name="ForAnyOp" Arg='C, func'/>
-##
-##  <Description>
-##  <C>ForAnyOp</C> is the operation called by <C>ForAny</C>
-##  if <A>C</A> is not an internal list.
-##  </Description>
-##  </ManSection>
-##
 DeclareOperation( "ForAnyOp", [ IsListOrCollection, IsFunction ] );