Improve and unify names (3)

RENAME.md

@@ -0,0 +1,81 @@
+
+This file gives further details on `rename.g` and it's associated files.
+
+## DESCRIPTION
+
+The `rename.g` file renames functions of the recog package and generates
+a table of renamed functions for the documentation.
+The `renamings_to_execute.csv` file specifies how to rename.
+The `renamings_history.csv` file stores the history of renamings
+and is used for the generation of the renaming table in the documentation.
+
+## INSTRUCTIONS
+
+Run the `rename.g` file with GAP from within the package directory.
+There are two possible applications for running the file.
+
+## APPLICATIONS
+
+The first one adresses the developers of the recog package.
+They can use this file to rename all occurences of a name `X`
+in all .g, .gd, .gi, .tst, and .xml files to a name `Y`.
+Below an example of this application is included.
+
+The second one adresses people who use the recog package as a dependency.
+They can apply the name changes that were executed inside the recog package to their own projects.
+
+## DETAILS
+
+The renamings_to_execute.csv and renamings_history.csv file have the following form:
+* First column `OLD NAME` contains the old name.
+* Second column `NEW NAME` contains the new name that is used now.
+* Third column `TYPE` contains the type used for GAPDoc references, e.g. `Func` or `Attr`.
+
+First let us discuss the case where the `renamings_to_execute.csv` file is not empty.
+The other case can be explained afterwards.
+
+First the `rename.g` file checks if the `renamings_to_execute.csv` file is syntactically correct.
+Then further sanity checks are done and on failure Errors/Warnings are printed.
+After successful checks all matches on word boundaries of the old name get
+replaced with the new name. The replacements are executed in all files with
+extensions .g, .gd, .gi, .tst, and .xml found in the directory tree rooted at '.'
+whereas all files in the .git folder are ignored.
+Afterwards the rows from the `renamings_to_execute.csv` file are added to
+the `renamings_history.csv` file. Then the renaming table for the
+documentation is generated from the `renamings_history.csv` file whereby
+renamings of the form `X_1 -> X_2 -> ... -> X_n` are printed
+in the documentation as `X_1 -> X_n`. Then the documentation of the recog package is regenerated.
+
+Now let us discuss the case where the `renamings_to_execute.csv` file is empty.
+Then the `rename.g` file attempts to execute the renamings in the order specified
+by the `renamings_history.csv` file. This is useful if you are developing code that is not yet integrated into the `recog` package, already performed some renamings and need to catch up with the latest ones.
+The replacements are executed as described in the first case.
+
+## EXAMPLE
+
+This example covers the use case for developers of the recog package.
+
+Create the `renamings_to_execute.csv` file, so it looks like this:
+
+    OLD NAME,NEW NAME,TYPE
+    FindHomDbPerm,MoreDescriptiveNewName,Attr
+
+Inside the package directory do:
+
+    gap rename.g
+
+Now the renamings that were stored inside the `renamings_to_execute.csv` file have been executed.
+Thus `FindHomDbPerm` got replaced by `MoreDescriptiveNewName`.
+
+It is recommended to run `gap tst/testquick.g` or `gap tst/testall.g` and ensure everything is still working:
+
+    gap tst/testall.g
+
+On failure you can always roll back to the last commit, i.e. the version before
+applying the renamings. For example one could type in the command `git reset --hard`.
+
+On success add and commit the changed files but make sure not to add the `renamings_to_execute.csv`:
+
+    git add *
+    git reset renamings_to_execute.csv
+    git commit

contrib/akos/examples4.g

@@ -485,7 +485,7 @@ if d>18 and d mod 16 = 2 and q mod 4 = 3 then
       od;
       list := reverse(Set(list));
       return list;
-  fi;  # largest prime factor of d-2
+  fi;  # largest prime image of d-2
 fi;
 
 end;

doc/afterrecog.xml

@@ -15,7 +15,7 @@ just by looking at the stored attribute values. Moreover, constructive
 membership tests can be performed using the function
 <Ref Func="SLPforElement"/>, thereby writing an arbitrary element
 in terms of the nice generators, which are stored in the attribute
-<Ref Attr="NiceGens"/>. If <K>fail</K> is returned, then the
+<Ref Attr="NiceGenerators"/>. If <K>fail</K> is returned, then the
 element in question does not lie in the recognised group or
 the recognition made an error.<P/>
 
@@ -26,9 +26,9 @@ Here is an example of a successful recognition tree:
 Group([ (1,2,3,4,5,6,7,8,9,10,11,12), (1,2), (13,14,15,16,17), (13,14) ])
 gap> ri := RecogniseGroup(g);
 #I  Finished rank 90 method "NonTransitive": success.
-#I  Going to the factor (depth=0, try=1).
+#I  Going to the image (depth=0, try=1).
 #I  Finished rank 95 method "MovesOnlySmallPoints": success.
-#I  Back from factor (depth=0).
+#I  Back from image (depth=0).
 #I  Calculating preimages of nice generators.
 #I  Creating 20 random generators for kernel.
 ....................
@@ -56,7 +56,7 @@ gap> x := PseudoRandom(g);
 (1,12)(2,5,9,11,10,3,4)(7,8)(13,14,16,15,17)
 gap> slp := SLPforElement(ri,x);
 <straight line program>
-gap> ResultOfStraightLineProgram(slp,NiceGens(ri));
+gap> ResultOfStraightLineProgram(slp,NiceGenerators(ri));
 (1,12)(2,5,9,11,10,3,4)(7,8)(13,14,16,15,17)]]>
 </Log>
 
@@ -89,7 +89,7 @@ generators, you can use the following function:
 <Returns>the size of the recognised group</Returns>
 <Description>
     This method calculates the size of the recognised group
-    by multiplying the size of the factor and the kernel recursively.
+    by multiplying the size of the image and the kernel recursively.
     It is assumed that leaf nodes know already or can calculate the
     size of their group.
 </Description>

doc/howtowritearecogmethod.autodoc

@@ -158,13 +158,13 @@ FindHomMethodsMatrix.BlockLowerTriangular := function(ri, G)
 
   # since we know exactly what kind of group we are looking
   # at, we don't want to run generic recognition on the
-  # factor group and the kernel. So we provide "hints" to
+  # image group and the kernel. So we provide "hints" to
   # ensure more appropriate recognition methods are applied
   # first.
 
-  # Give hint to factor
-  forfactor(ri).blocks := ri!.blocks;
-  Add(forfactor(ri).hints,
+  # Give hint to image
+  InitDataForImageNode(ri).blocks := ri!.blocks;
+  Add(InitDataForImageNode(ri).hints,
       rec( method := FindHomMethodsMatrix.BlockDiagonal,
            rank := 2000,
            stamp := "BlockDiagonal" ) );
@@ -174,11 +174,11 @@ FindHomMethodsMatrix.BlockLowerTriangular := function(ri, G)
   findgensNmeth(ri).args := [];
 
   # Give hint to kernel N
-  Add(forkernel(ri).hints,
+  Add(InitDataForKernelNode(ri).hints,
       rec( method := FindHomMethodsMatrix.LowerLeftPGroup,
            rank := 2000,
            stamp := “LowerLeftPGroup" ));
-  forkernel(ri).blocks := ri!.blocks;
+  InitDataForKernelNode(ri).blocks := ri!.blocks;
 
   # This function always succeeds, because it is only
   # called for inputs for which it is known to apply.

doc/recognition.xml

@@ -94,7 +94,7 @@ we first summarise it in steps:
     calls itself with the image of the homomorphism. Note that this
     might use another database of recognition methods because the
     homomorphism might change the representation of the group.</Item>
-<Item>After successful recognition of the factor group the procedure has
+<Item>After successful recognition of the image group the procedure has
     to recognise the kernel of the homomorphism. The first step for this
     is to find generators. If they are not already known from the
     <C>FindHomomorphism</C> method, they are created by producing random
@@ -119,8 +119,8 @@ group as a straight line program in the generators as follows:
 
 <Enum>
 <Item>Map the element through the homomorphism.</Item>
-<Item>Write the element in the factor group as a product of the nice
-    generators in the factor group.</Item>
+<Item>Write the element in the image group as a product of the nice
+    generators in the image group.</Item>
 <Item>Apply the resulting straight line program to the preimages of those
     nice generators and calculate the quotient, which will now lie in
     the kernel.</Item>
@@ -164,7 +164,7 @@ whether or not the method works in projective mode. For permutation groups,
 set this to <K>false</K>. The result is either <K>fail</K> or
 <K>false</K> if the method fails or a recognition info record <C>ri</C>.
 If the method created a leaf then <C>ri</C> will be a leaf, otherwise
-it will have the attribute <Ref Attr="Homom"/> set, but no factor or
+it will have the attribute <Ref Attr="Homom"/> set, but no image or
 kernel have been created or recognised yet. You can use for example
 the methods in <Ref Var="FindHomMethodsPerm"/> or
 <Ref Var="FindHomMethodsMatrix"/> or <Ref Var="FindHomMethodsProjective"/>
@@ -190,19 +190,19 @@ A recognition info record is a &GAP; component object. It is a member
 of the family
 
 <ManSection>
-<Fam Name="RecognitionInfoFamily"/>
+<Fam Name="RecogNodeFamily"/>
 </ManSection>
 
 and is in the category
 
 <ManSection>
-    <Filt Name="IsRecognitionInfo" Type="Category"/>
+    <Filt Name="IsRecogNode" Type="Category"/>
 </ManSection>
 
 and is <Ref Filt="IsAttributeStoringRep" BookName="Ref"/>, such that we can
 define attributes for it, the values of which are stored once they are
 known. A recognition info record always represents a whole binary tree of such
-records, see the attributes <Ref Attr="RIFac"/> and <Ref Attr="RIKer"/>
+records, see the attributes <Ref Attr="ImageRecogNode"/> and <Ref Attr="KernelRecogNode"/>
 below. <P/>
 
 The following filters are defined for recognition info records:
@@ -214,16 +214,16 @@ The following attributes are defined for recognition info records:
 
 <#Include Label="Grp">
 <#Include Label="Homom">
-<#Include Label="NiceGens">
-<#Include Label="pregensfac">
-<#Include Label="RIFac">
-<#Include Label="RIKer">
-<#Include Label="RIParent">
+<#Include Label="NiceGenerators">
+<#Include Label="PreImagesOfNiceGeneratorsOfImageNode">
+<#Include Label="ImageRecogNode">
+<#Include Label="KernelRecogNode">
+<#Include Label="ParentRecogNode">
 <#Include Label="fhmethsel">
 <#Include Label="slpforelement">
 <#Include Label="SLPforElement">
 <#Include Label="StdPresentation">
-<#Include Label="methodsforfactor">
+<#Include Label="methodsforimage">
 
 <ManSection>
 <Attr Name="validatehomominput" Arg="ri, x"/>
@@ -269,10 +269,10 @@ the original generators and the nice generators for a node.
 They are used to transport this information from a successful find
 homomorphism method up to the recursive recognition function:
 
-<#Include Label="calcnicegens">
-<#Include Label="CalcNiceGensGeneric">
-<#Include Label="CalcNiceGensHomNode">
-<#Include Label="CalcNiceGens">
+<#Include Label="RECOG_CalcNiceGeneratorsFunctionOfRecogNode">
+<#Include Label="CalcNiceGeneratorsForLeafNode">
+<#Include Label="CalcNiceGeneratorsForSplitNode">
+<#Include Label="CalcNiceGenerators">
 <#Include Label="slptonice">
 
 The following three attributes are concerned with the administration of the
@@ -398,11 +398,11 @@ find kernel methods.
 
 The following attributes are used to give a successful find homomorphism
 method further possibilities to transport knowledge about the group
-recognised by the current recognition info record to the factor or
+recognised by the current recognition info record to the image or
 kernel of the found homomorphism:
 
 <ManSection>
-<Attr Name="forkernel" Arg="ri"/>
+<Attr Name="InitDataForKernelNode" Arg="ri"/>
 <Description>
     This attribute is initialised to a record with only the component
     <C>hints</C> bound to an empty list at the beginning of the
@@ -424,7 +424,7 @@ kernel of the found homomorphism:
 </ManSection>
 
 <ManSection>
-<Attr Name="forfactor" Arg="ri"/>
+<Attr Name="InitDataForImageNode" Arg="ri"/>
 <Description>
     This attribute is initialised to a record with only the component
     <C>hints</C> bound to an empty list at the beginning of the
@@ -433,15 +433,15 @@ kernel of the found homomorphism:
     example an invariant subspace of a matrix group) into this record.
     When a homomorphism is found and recognition goes on in its
     image, the value of this attribute is taken as initialisation data
-    for the newly created recognition info record for the factor. Thus,
+    for the newly created recognition info record for the image. Thus,
     information is transported down to the recognition process for the
-    factor. The component <C>hints</C> is special insofar as it has to
+    image. The component <C>hints</C> is special insofar as it has to
     contain records describing find homomorphism methods which might be
     particularly successful. They are prepended to the find homomorphism
     method database such that they are called before any other methods.
     This is a means to give hints to the recognition procedure in the
-    factor, because often during the finding of a homomorphism knowledge
-    is acquired which might help the recognition of the factor.
+    image, because often during the finding of a homomorphism knowledge
+    is acquired which might help the recognition of the image.
 </Description>
 </ManSection>
 
@@ -466,7 +466,7 @@ This attribute returns a function that compares two elements of the
 group being recognised.  Usually this is
 just the operation <Ref Oper="EQ" BookName="Ref"/> but for projective
 groups it is a special function checking for equality up to a scalar
-factor. In
+image. In
 generic code, one should always use the result of this attribute to
 compare two elements such that the code works also for
 projective groups. Find homomorphism methods usually do not have to
@@ -615,10 +615,10 @@ A successful find homomorphism method has the following duties:
     nice generators in terms of the original generators into the attribute
     <Ref Attr="slptonice"/>. In that case, the generic frame work takes
     care of the rest. The third possibility is to store a function
-    into the value of the attribute <Ref Attr="calcnicegens"/> which
+    into the value of the attribute <Ref Attr="RECOG_CalcNiceGeneratorsFunctionOfRecogNode"/> which
     can calculate preimages of the nice generators in terms of preimages
     of the original generators. See the function
-    <Ref Func="CalcNiceGensGeneric"/> for an example of such a function.
+    <Ref Func="CalcNiceGeneratorsForLeafNode"/> for an example of such a function.
 </Item>
 <Mark>for non-leaves: the homomorphism itself</Mark>
 <Item>
@@ -627,7 +627,7 @@ A successful find homomorphism method has the following duties:
     group in the attribute <Ref Attr="Homom"/>. Note that if your homomorphism
     changes the representation (for example going from matrix groups to
     permutation groups), you will have to set the attribute
-    <Ref Attr="methodsforfactor"/> accordingly. Also,
+    <Ref Attr="methodsforimage"/> accordingly. Also,
     <Ref Attr="ValidateHomomInput"/> may be set to a function which returns
     <K>false</K> for values which may cause <Ref Attr="Homom"/> to
     produce the wrong answer, or error.
@@ -652,20 +652,20 @@ A successful find homomorphism method has the following duties:
 <Mark>additional information</Mark>
 <Item>
     A find homomorphism method may store any data into the attributes
-    <Ref Attr="forkernel"/> and <Ref Attr="forfactor"/>, which both are
+    <Ref Attr="InitDataForKernelNode"/> and <Ref Attr="InitDataForImageNode"/>, which both are
     records. Components in these
     record that are bound during the recognition will be copied into
-    the recognition info record of the kernel and factor respectively
+    the recognition info record of the kernel and image respectively
     of a found homomorphism
     upon creation and thus are available to all find homomorphism
-    methods called for the kernel and factor. This feature might be
+    methods called for the kernel and image. This feature might be
     interesting to transport information that is relevant for the
-    recognition of the kernel or factor and was acquired during the recognition
+    recognition of the kernel or image and was acquired during the recognition
     of <A>G</A> itself.<P/> A special role is played by the component
     <C>hints</C> in both of the above records,
     which can hold a list of records describing find
     homomorphism methods that shall be tried first when recognising the
-    kernel or factor. <P/>
+    kernel or image. <P/>
     In addition, a find homomorphism method might set the attribute
     <Ref Attr="immediateverification"/> to <K>true</K>, if it considers the
     problem of finding kernel generators particularly difficult.
@@ -691,7 +691,7 @@ group say <M>H</M> with kernel <M>N</M>. It first maps <A>x</A> via
 the homomorphism to <M>H</M> and uses the recognition information there
 to write it as a straight line program in terms of the nice generators of
 <M>H</M>. Then it applies this straight line program to the preimages
-of those nice generators (see <Ref Attr="pregensfac"/>)
+of those nice generators (see <Ref Attr="PreImagesOfNiceGeneratorsOfImageNode"/>)
 thereby finding an element <M>y</M> of <M>G</M> with <M>x \cdot y^{-1}</M>
 lying in the kernel <M>N</M>. <P/>
 Then the function writes this element

doc/renaming.xml

@@ -0,0 +1,16 @@
+<Chapter Label="Renaming">
+<Heading>Renaming</Heading>
+
+<#Include SYSTEM "renaming_index.xml">
+
+Many of the names in the recog package were found
+to be unintuitive or inconsistent with other names.
+For these reasons the names were changed to be more descriptive
+and to follow the internal consistency of &GAP;.
+In this chapter a dictionary from old to new names is included.
+The meanings of the old names for components of a recognition info record are described in
+Section 2.6 "Components of the recognition info record" of the article <Cite Key="NS06"/>.
+
+<#Include SYSTEM "renaming_table.xml">
+
+</Chapter>

doc/renaming_index.xml

@@ -0,0 +1,14 @@
+<Index Key="RecognitionInfoFamily"><C>RecognitionInfoFamily</C></Index>
+<Index Key="IsRecognitionInfo"><C>IsRecognitionInfo</C></Index>
+<Index Key="RIFac"><C>RIFac</C></Index>
+<Index Key="RIKer"><C>RIKer</C></Index>
+<Index Key="RIParent"><C>RIParent</C></Index>
+<Index Key="methodsforfactor"><C>methodsforfactor</C></Index>
+<Index Key="forfactor"><C>forfactor</C></Index>
+<Index Key="forkernel"><C>forkernel</C></Index>
+<Index Key="NiceGens"><C>NiceGens</C></Index>
+<Index Key="pregensfac"><C>pregensfac</C></Index>
+<Index Key="calcnicegens"><C>calcnicegens</C></Index>
+<Index Key="CalcNiceGensGeneric"><C>CalcNiceGensGeneric</C></Index>
+<Index Key="CalcNiceGens"><C>CalcNiceGens</C></Index>
+<Index Key="CalcNiceGensHomNode"><C>CalcNiceGensHomNode</C></Index>