address some more comments

doc/ref/makedocreldata.g

@@ -53,6 +53,7 @@ GAPInfo.ManualDataRef:= rec(
     "../../lib/cyclotom.g",
     "../../lib/cyclotom.gd",
     "../../lib/cyclotom.gi",
+    "../../lib/dlog.gd",
     "../../lib/dict.gd",
     "../../lib/domain.gd",
     "../../lib/extlset.gd",

doc/ref/numtheor.xml

@@ -42,6 +42,7 @@
 
 <#Include Label="OrderMod">
 <#Include Label="LogMod">
+<#Include Label="DLog">
 <#Include Label="PrimitiveRootMod">
 <#Include Label="IsPrimitiveRootMod">
 

lib/dlog.gd

@@ -14,22 +14,44 @@
 
 #############################################################################
 ##
-#F  _DLog( <base>, <x>[, <m>] )
+#F  DLog( <base>, <x>[, <m>] )
 ##
+##  <#GAPDoc Label="DLog">
 ##  <ManSection>
-##  <Func Name="_DLog" Arg='base, x[, m]'/>
-##
+##  <Func Name="DLog" Arg="base, x[, m]"/>
+##  <Returns>an integer</Returns>
 ##  <Description>
 ##  <Index Subkey="discrete">logarithm</Index>
-##  returns a discrete logarithm of <A>x</A> w.r.t. the basis <A>base</A>,
-##  i. e., an integer <M>l</M> such that <M><A>base</A>^l = <A>x</A></M>
-##  holds, if such a number exists.
-##  Otherwise <K>fail</K> is returned.
+##  The argument  <A>base</A> must  be a  multiplicative element  and <A>x</A>
+##  must lie in the cyclic group  generated by <A>base</A>. The third argument
+##  <A>m</A>  must  be the  order  of  <A>base</A>  or its  factorization.  If
+##  <A>m</A> is  not given, it  is computed  first. This function  returns the
+##  discrete logarithm, that is an integer <M>e</M> such that <A>base</A><M>^e
+##  = </M> <A>x</A>.
+##  <P/>
+##  If  <A>m</A>  is  prime  then  Shanks'  algorithm  is  used  (which  needs
+##  <M>O(\sqrt{<A>m</A>})</M> space and time). Otherwise  let <A>m</A> <M> = r
+##  l</M> and  <M>e =  a +  b r</M>  with <M>0  \leq a  &lt; r</M>.  Then <M>a
+##  =</M>  <C>DLog</C><M>(<A>base</A>^l, <A>x</A>^l,  r)</M> and  <M>b =  </M>
+##  <C>DLog</C><M>(<A>base</A>^r, <A>x</A>/<A>base</A>^a, l)</M>.
 ##  <P/>
-##  The order of <A>base</A> or its factorization can be given as <A>m</A>.
+##  This function is used for a method of <Ref Oper="LogFFE"/>.
+##
+##  <Example>
+##  gap> q:= 67^12;
+##  8182718904632857144561
+##  gap> z:= Z(q);;
+##  gap> DLog(z, z+1);
+##  2874413785388345993274
+##  gap> DLog(z, z^2+1);
+##  1667375214152688471247
+##  gap> DLog(z, Z(67));
+##  123980589464134199160
+##  </Example>
 ##  </Description>
 ##  </ManSection>
+##  <#/GAPDoc>
 ##
-DeclareGlobalFunction( "_DLog" );
+DeclareGlobalFunction( "DLog" );
 
-DeclareGlobalFunction( "_DLogShanks" );
+DeclareGlobalFunction( "DLogShanks" );

lib/dlog.gi

@@ -15,13 +15,13 @@
 
 #############################################################################
 ##
-#F  _DLogShanks( <base>, <x>, <r> )
+#F  DLogShanks( <base>, <x>, <r> )
 ##
 ##  Let <base> be a multiplicative element of order <r>.
 ##  Return an integer l such that <x> = <base>^l holds,
 ##  or 'fail' if no such l exists.
 ##
-InstallGlobalFunction( _DLogShanks, function(base, x, r)
+InstallGlobalFunction( DLogShanks, function(base, x, r)
   local rr, baby, ord, giant, t, pos, i, j;
   rr := RootInt(r, 2);
   baby := [One(base)];
@@ -51,15 +51,15 @@ end );
 
 #############################################################################
 ##
-#F  _DLog( <base>, <x>[, <m>] )
+#F  DLog( <base>, <x>[, <m>] )
 ##
 ##  recursive method, <m> can be the order m of <base> or its factorization
 ##  Let r be the largest prime factor of m, then we use
 ##     <base>^e = <x> with e = a + b*r where 0 <= a < r and
 ##     0 <= b < m/r,
-##  and compute a with _DLogShanks and b by recursion.
+##  and compute a with DLogShanks and b by recursion.
 ##
-InstallGlobalFunction( _DLog, function(base, x, m...)
+InstallGlobalFunction( DLog, function(base, x, m...)
   local r, mm, mp, a, b;
   if Length(m) = 0 then
     m := Order(base);
@@ -70,16 +70,16 @@ InstallGlobalFunction( _DLog, function(base, x, m...)
     m := Factors(m);
   fi;
   if Length(m) = 1 then
-    return _DLogShanks(base, x, m[1]);
+    return DLogShanks(base, x, m[1]);
   fi;
   r := m[Length(m)];
   mm := m{[1..Length(m)-1]};
   mp := Product(mm);
-  a := _DLogShanks(base^mp, x^mp, r);
+  a := DLogShanks(base^mp, x^mp, r);
   if a = fail then
     return fail;
   fi;
-  b := _DLog(base^r, x/(base^a), mm);
+  b := DLog(base^r, x/(base^a), mm);
   if b = fail then
     return fail;
   fi;
@@ -104,5 +104,5 @@ BindGlobal( "DoDLog", function(x, base)
   else
     e := 1;
   fi;
-  return _DLog(base, x, o) * e;
+  return DLog(base, x, o) * e;
 end );

tst/testinstall/dlog.tst

@@ -1,21 +1,21 @@
 #@local R, o
 gap> START_TEST( "dlog.tst" );
 
-# _DLog
+# DLog
 gap> R:= Integers mod 71;;  o:= One( R );;
-gap> _DLog( 2*o, 4*o );
+gap> DLog( 2*o, 4*o );
 2
 gap> R:= Integers mod 17;;  o:= One( R );;
-gap> _DLog( 2*o, 3*o );
+gap> DLog( 2*o, 3*o );
 fail
 gap> R:= Integers mod 9;;  o:= One( R );;
-gap> _DLog( 2*o, 4*o );
+gap> DLog( 2*o, 4*o );
 2
-gap> _DLog( 3*o, 4*o );
+gap> DLog( 3*o, 4*o );
 Error, <obj> is not invertible
-gap> ForAll( Primes, p -> p = 2 or _DLog( Z(p^2), Z(p^2)^2 ) = 2 );
+gap> ForAll( Primes, p -> p = 2 or DLog( Z(p^2), Z(p^2)^2 ) = 2 );
 true
-gap> ForAll( Primes, p -> p = 2 or _DLog( Z(p^2)^2, Z(p^2) ) = fail );
+gap> ForAll( Primes, p -> p = 2 or DLog( Z(p^2)^2, Z(p^2) ) = fail );
 true
 
 #