[Rd] branch cuts of log() and sqrt()

[Robin Hankin]

Dear developers

Neither Math.Rd nor Log.Rd mention the branch cuts
that appear for complex arguments.  I think it's important
to include such information.

Please find following two context diffs for Log.Rd and Math.Rd.

[The pedants amongst us will observe that
both sqrt() and log() have a branch point at complex
infinity, which is not mentioned in the patch.  Comments
anyone?]



rksh




245-10:~/scratch/R-devel/src/library/base/man% diff -c  Log.Rd  
new_Log.Rd
*** Log.Rd      Fri Jul 27 16:51:42 2007
--- new_Log.Rd  Tue Dec 18 08:57:03 2007
***************
*** 66,71 ****
--- 66,75 ----
     \code{logb} is a wrapper for \code{log} for compatibility with  
S.  If
     (S3 or S4) methods are set for \code{log} they will be dispatched.
     Do not set S4 methods on \code{logb} itself.
+
+   For complex arguments, the branch cut is standard: there is a branch
+   point at zero and a cut along the negative real axis; continuity
+   is from above.
   }
   \section{S4 methods}{
     \code{exp}, \code{expm1}, \code{log}, \code{log10}, \code{log2} and
245-10:~/scratch/R-devel/src/library/base/man%




245-10:~/scratch/R-devel/src/library/base/man% diff -c  Math.Rd  
new_Math.Rd
*** Math.Rd     Fri Jul 27 16:51:44 2007
--- new_Math.Rd Tue Dec 18 09:01:35 2007
***************
*** 22,32 ****
   \details{
     These are generic functions: methods can be defined for them
     individually or via the \code{\link[base:groupGeneric]{Math}}
!   group generic.  For complex arguments (and the default method),  
\code{z},
!   \code{abs(z) == \link{Mod}(z)} and \code{sqrt(z) == z^0.5}.

     \code{abs(x)} returns an \code{\link{integer}} vector when \code 
{x} is
     \code{integer} or \code{\link{logical}}.
   }
   \section{S4 methods}{
     Both are S4 generic and members of the
--- 22,39 ----
   \details{
     These are generic functions: methods can be defined for them
     individually or via the \code{\link[base:groupGeneric]{Math}}
!   group generic.

     \code{abs(x)} returns an \code{\link{integer}} vector when \code 
{x} is
     \code{integer} or \code{\link{logical}}.
+
+   For complex arguments (and the default method), \code{z},
+   \code{abs(z) == \link{Mod}(z)} and \code{sqrt(z) == z^0.5}.
+
+   The branch cut of \code{sqrt()} is standard: there is a branch point
+   at zero and a cut along the negative real axis; continuity is from
+   above.
+
   }
   \section{S4 methods}{
     Both are S4 generic and members of the
245-10:~/scratch/R-devel/src/library/base/man%



--
Robin Hankin
Uncertainty Analyst and Neutral Theorist,
National Oceanography Centre, Southampton
European Way, Southampton SO14 3ZH, UK
  tel  023-8059-7743