<!-- ------------------------------------------------------------------- -->
<!--                                                                     -->
<!--  others.xml          Utils documentation                Stefan Kohl -->
<!--                                                   Sebastian Gutsche -->
<!--                                                            Max Horn -->
<!--  Copyright (C) 2015-2017, The GAP Group                             --> 
<!--                                                                     -->
<!-- ------------------------------------------------------------------- -->

<?xml version="1.0" encoding="UTF-8"?>

<Chapter Label="chap-others">
<Heading>Various other functions</Heading>


<Section Label="sec-folder-ops">
<Heading>Operations on folders</Heading>

<ManSection>
  <Func Name="FindMatchingFiles" 
        Arg="pkg dirs extns"/>
  <Func Name="CreateDirIfMissing" 
        Arg="str"/>
<Description>
These functions have been transferred from package &AutoDoc; 
where they were named <C>AutoDoc_FindMatchingFiles</C> 
and <C>AutoDoc_CreateDirIfMissing</C>. 
<P/>
<C>FindMatchingFiles</C> scans the given (by name) subdirectories 
of a package directory for files with one of the given extensions, 
and returns the corresponding filenames, 
as paths relative to the package directory.
<P/>
<C>CreateDirIfMissing</C> checks whether the given directory exists 
and, if not, attempts to create it. 
In either case <C>true</C> is returned. 
<P/>
<E>Warning:</E> this function relies on the undocumented library function 
<C>CreateDir</C>, so use it with caution. 
<P/>
</Description>
</ManSection>
<P/>
<Example>
<![CDATA[
gap> FindMatchingFiles( "utils", [ "/", "tst" ], [ "g", "txt" ] );
[ "/LICENSE.txt", "/PackageInfo.g", "/init.g", "/makedoc.g", "/read.g", 
  "tst/testall.g" ]
gap> CreateDirIfMissing( "/Applications/gap/temp/" );
true
]]>
</Example>


</Section>


<Section Label="sec-log2html">
<Heading>File operations</Heading>

<ManSection>
  <Func Name="Log2HTML" 
        Arg="filename"/>
<Description>
This function has been transferred from package &RCWA;. 
<P/>
This function converts the &GAP; logfile <File>filename</File> to HTML. 
The extension of the input file must be <File>*.log</File>. 
The name of the output file is the same as the one of the input file 
except that the extension <File>*.log</File> is replaced by <File>*.html</File>. 
There is a sample CSS file in <File>utils/doc/gaplog.css</File>, 
which you can adjust to your taste. 
<P/>
</Description>
</ManSection>
<P/>
<Example>
<![CDATA[
gap> LogTo("mar2.log");
gap> FindMatchingFiles( "utils", [""], ["g"] ); 
[ "/PackageInfo.g", "/init.g", "/makedoc.g", "/read.g" ]
gap> LogTo();
gap> Log2HTML( "mar2.log" );
gap> FindMatchingFiles( "utils", [""], ["html", "log"] );
[ "/mar2.html", "/mar2.log" ]
]]>
</Example>

</Section>


<Section Label="sec-latex">
<Heading>&LaTeX; strings</Heading>

<ManSection>
  <Func Name="IntOrOnfinityToLaTeX" 
        Arg="n"/>
<Description>
This function has been transferred from package &ResClasses;. 
<P/>
<C>IntOrInfinityToLaTeX(n)</C> returns the &LaTeX; string for <A>n</A>. 
<P/>
</Description>
</ManSection>
<P/>
<Example>
<![CDATA[
gap> IntOrInfinityToLaTeX( 10^3 );
"1000"
gap> IntOrInfinityToLaTeX( infinity );
"\\infty"
]]>
</Example>

<ManSection>
  <Func Name="LaTeXStringFactorsInt" 
        Arg="n"/>
<Description>
This function has been transferred from package &RCWA;. 
<P/>
It returns the prime factorization of the integer <M>n</M> as a string in 
&LaTeX; format.
<P/>
</Description>
</ManSection>
<P/>
<Example>
<![CDATA[
gap> LaTeXStringFactorsInt( Factorial(12) );
"2^{10} \\cdot 3^5 \\cdot 5^2 \\cdot 7 \\cdot 11"
]]>
</Example>


</Section>


<Section Label="sec-methods">
<Heading>Applicable methods</Heading>

<ManSection>
  <Func Name="PrintApplicableMethod" 
        Arg="arg"/>
<Description>
This function combines calls to <C>ApplicableMethod</C>, <C>FilenameFunc</C>, 
<C>StartlineFunc</C> and <C>EndlineFunc</C> and prints the location of the file 
containing the method found, and a listing of that method. 
In its simplest form it is called as <C>PrintApplicableMethod(f,L)</C> 
for a function <C>f</C> and a list of parameters <C>L</C>. 
Alternatively, it is called as <C>PrintApplicableMethod(f,L,0,n)</C> 
and then prints the method returned by <C>ApplicableMethod(f,L,0,n)</C>. 
<P/>
</Description>
</ManSection>
<P/>
<Example>
<![CDATA[
gap> PrintApplicableMethod( IsCyclic, [ Group((1,2,3),(4,5)) ] );
this method is contained in lines [30,36] of file:
    /Applications/gap/gapdev/lib/grp.gi
function ( G )
    if Length( GeneratorsOfGroup( G ) ) = 1  then
        return true;
    else
        return TRY_NEXT_METHOD;
    fi;
    return;
end
gap> PrintApplicableMethod( IsCyclic, [ Group((1,2,3),(4,5)) ], 0, 2 );
this method is contained in lines [41,63] of file:
    /Applications/gap/gapdev/lib/grp.gi
function ( G )
    if HasGeneratorsOfGroup( G ) and Length( GeneratorsOfGroup( G ) ) = 1
         then
        SetMinimalGeneratingSet( G, GeneratorsOfGroup( G ) );
        return true;
    elif not IsCommutative( G )  then
        return false;
    elif IsFinite( G )  then
        return ForAll( Set( FactorsInt( Size( G ) ) ), function ( p )
                return 
                 Index( G, 
                     SubgroupNC( G, 
                       List( GeneratorsOfGroup( G ), function ( g )
                              return g ^ p;
                          end ) ) ) = p;
            end );
    else
        return AbelianInvariants( G ) = [ 0 ];
    fi;
    return;
end
]]>
</Example>

</Section>

<Section Label="sec-magma">
<Heading>Conversion to &Magma; string</Heading>

<ManSection>
  <Func Name="ConvertToMagmaInputString" 
        Arg="arg"/>
<Description>
The function <C>ConvertToMagmaInputString( obj [, str] )</C> 
attempts to output a string <C>s</C> which can be read into 
&Magma; <Cite Key="MAGMA" />
so as to produce the same group in that computer algebra system. 
In the second form the user specifies the name of the resulting object, 
so that the output string has the form <C>"str := ..."</C>. 
When <C>obj</C> is a permutation group, the operation 
<C>PermGroupToMagmaFormat(obj)</C> is called. 
This function has been taken from <File>other.gi</File> in the main library 
where it was called <C>MagmaInputString</C>. 
When <C>obj</C> is a pc-group, the operation 
<C>PcGroupToMagmaFormat(obj)</C> is called. 
This function was private code of Max Horn. 
When <C>obj</C> is a matrix group over a finite field, 
the operation <C>MatrixGroupToMagmaFormat(obj)</C> is called. 
This function is a modification of private code of Frank L&#xfc;beck. 
<P/>
Hopefully code for other types of group will be added in due course. 
<P/>
These functions should be considered <E>experimental</E>, 
and more testing is desirable. 
<P/>
</Description>
</ManSection>
<P/>
<Example>
<![CDATA[
gap> ConvertToMagmaInputString( Group( (1,2,3,4,5), (3,4,5) ) );
"PermutationGroup<5|(1,2,3,4,5),\n(3,4,5)>;\n"
gap> ConvertToMagmaInputString( Group( (1,2,3,4,5) ), "c5" );        
"c5:=PermutationGroup<5|(1,2,3,4,5)>;\n"
gap> ConvertToMagmaInputString( SmallGroup( 24, 12 ) );      
"PolycyclicGroup< f1,f2,f3,f4 |\nf1^2,\nf2^3,\nf3^2,\nf4^2,\nf2^f1 = f2^2,\nf3\
^f1 = f4,\nf3^f2 = f4,\nf4^f1 = f3,\nf4^f2 = f3*f4\n>;\n"
gap> ConvertToMagmaInputString( CyclicGroup( IsPcGroup, 7 ), "c7" );
"c7:=PolycyclicGroup< f1 |\nf1^7\n>;\n"
gap> M := GL(2,5);;  Size(M); 
480
gap> s1 := ConvertToMagmaInputString( M );
"F := GF(5);\nP := GL(2,F);\ngens := [\nP![2,0,0,1],\nP![4,1,4,0]\n];\nsub<P |\
 gens>;\n"
gap> Print( s1 );
F := GF(5);
P := GL(2,F);
gens := [
P![2,0,0,1],
P![4,1,4,0]
];
sub<P | gens>;
gap> n1 := [ [ Z(9)^0, Z(9)^0 ], [ Z(9)^0, Z(9) ] ];;
gap> n2 := [ [ Z(9)^0, Z(9)^3 ], [ Z(9)^4, Z(9)^2 ] ];;
gap> N := Group( n1, n2 );;  Size( N );
5760
gap> s2 := ConvertToMagmaInputString( N, "gpN" );;
gap> Print( s2 );
F := GF(3^2);
P := GL(2,F);
w := PrimitiveElement(F);
gens := [
P![ 1, 1, 1,w^1],
P![ 1,w^3, 2,w^2]
];
gpN := sub<P | gens>;
]]>
</Example>

</Section>



</Chapter>

