R devel - Mar 2025 - request for discussion on lonely doc patch suggestion

Aki Vehtari and I suggested a revision to some of the man pages 
involving NA/is.nan/is.na about a year ago, but it never seems to have 
gotten any traction.

https://bugs.r-project.org/show_bug.cgi?id=18691

Discussion here:

https://fediscience.org/@avehtari at bayes.club/112043521852737720

   The patch file is attached (also available at bugzilla, if it doesn't 
get through to the list). I find the patch format a little hard to read, 
so I'm reproducing just the *new* text below.

   Any ideas or suggestions would be welcome.

   cheers
    Ben Bolker


----
src/library/base/man/NA.Rd:

  The generic function \code{is.na} indicates which elements are missing
   (\code{NA}) or \sQuote{Not a Number} (\code{link{NaN}}).

in examples from this page:

is.na(c(1, NA, NA_real_, NaN))        #> FALSE  TRUE  TRUE  TRUE
is.na(paste(c(1, NA, NA_real_, NaN))) #> FALSE FALSE FALSE FALSE

# When NaN should not be considered as missing value
is.na(c(1, NA, NA_real_, NaN)) & !is.nan(c(1, NA, NA_real_, NaN))

   (POSSIBLE EDITS: more explanatory comments, especially explaining 
that paste() is converting NA values to "NA" strings ...)

---
 From src/library/base/man/is.finite.Rd:

whereas \code{NaN} means \sQuote{Not a Number}.  \code{Inf} and
   \code{NaN} are class of \code{numeric} and type of \code{double},
   and can be used in real and imaginary parts of complex values, but not
   as values in integer vectors.

  (POSSIBLE EDITS: "class of", "type of" -> "of
class"/"of type" or
"have class"/"have type" ?)

   in "See Also":

\code{\link{NA}}, \sQuote{\emph{Not Available}}, which is usually used
   to denote a missing value. The default mode of \code{NA} is
   \code{logical}, unlike \code{NaN}, which is always of mode
   \code{double}.

---
 From src/library/base/man/numeric.Rd

\code{is.numeric} is a more general test of an object being
   interpretable as numbers. These include special numeric objects
   \code{\link{Inf}}, \code{\link{NaN}}, \code{\link{NA_integer_}},
   and \code{\link{NA_real_}}.

-------------- next part --------------
An embedded and charset-unspecified text was scrubbed...
Name: nan.txt
URL:
<https://stat.ethz.ch/pipermail/r-devel/attachments/20250324/f5c9606b/attachment.txt>

I sent some comments directly to Ben.  I just want to reply publicly to 
this part:

On 2025-03-24 1:18 p.m., Ben Bolker wrote:
>     The patch file is attached (also available at bugzilla, if it
doesn't
> get through to the list). I find the patch format a little hard to read,
> so I'm reproducing just the *new* text below.
I agree absolutely about the lack of readability of patch files.  A side 
by side display is much nicer.  If anyone out there isn't using one, you 
should.

I really like the one I use ("Beyond Compare"), but it's not open 
source.  I've been using it for a very long time (20 years or more, I 
think), and I suspect there are very good open source competitors out 
there now (and may have been for all the time I've been using BC). 
Suggestions?

Duncan Murdoch