doc: basic documentation for constructors

doc/ref/methsel.xml

@@ -75,6 +75,62 @@ and then set the attribute tester for the object to <K>true</K>.
 </Section>
 
 
+<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+<Section Label="Constructors">
+<Heading>Constructors</Heading>
+
+Constructors are a special type of operation used to make new
+objects. The key difference is that the first argument in a call to a
+constructor is a filter <Ref Sect="Filters"/> rather than an
+object. This signifies filters in which the constructed object must
+lie and method selection is based on the value of this filter, rather
+than its type.
+
+<Example><![CDATA[
+gap> DeclareConstructor("XCons",[IsMagma,IsInt]);
+gap> InstallMethod(XCons, [IsGroup, IsInt], function(t,x) return CyclicGroup(x); end);
+gap> InstallMethod(XCons, [IsPermGroup, IsInt], function(t,x) return SymmetricGroup(x); end);
+gap> InstallMethod(XCons, [IsSemigroup, IsInt], function(t,x) return FullTransformationMonoid(x); end);
+gap> XCons(IsGroup,3);
+<pc group of size 3 with 1 generators>
+gap> XCons(IsPermGroup,3);
+Sym( [ 1 .. 3 ] )
+gap> XCons(IsSemigroup,4);
+<full transformation monoid of degree 4>
+]]></Example>
+
+The example above shows sonme basic examples (usually a constructor
+will produce isomorphic objects in different representations, not
+different objects as in this case).
+
+If no method has been installed which guarantees to produce a suitable
+objecty, a "No Method Found" error will be returned.
+<Log><![CDATA[
+gap> XCons(IsFullTransformationMonoid,4);
+Error, no method found! For debugging hints type ?Recovery from NoMethodFound
+Error, no 1st choice method found for `XCons' on 2 arguments called from
+<function "HANDLE_METHOD_NOT_FOUND">( <arguments> )
+ called from read-eval loop at line 8 of *stdin*
+you can 'quit;' to quit to outer loop, or
+you can 'return;' to continue
+brk> quit;
+gap> XCons(IsNilpotentGroup,4);
+Error, no method found! For debugging hints type ?Recovery from NoMethodFound
+Error, no 1st choice method found for `XCons' on 2 arguments called from
+<function "HANDLE_METHOD_NOT_FOUND">( <arguments> )
+ called from read-eval loop at line 9 of *stdin*
+you can 'quit;' to quit to outer loop, or
+you can 'return;' to continue
+brk>
+]]></Log>
+
+Note that in both these cases there are methods that actually produce
+results of the required types, but they have not been installed with
+this information, so are not selected.
+
+</Section>
+
+
 <!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
 <Section Label="Method Installation">
 <Heading>Method Installation</Heading>