[R] Where are usages like "== 2L" documented?

Duncan Murdoch murdoch at stats.uwo.ca
Tue Nov 17 12:05:48 CET 2009


I think your suggestions below indicate a difference in documentation 
philosophy between us.  I believe that things should be documented well 
in one place, and it should be easy to find that one place; you seem to 
be suggesting spreading out bits and pieces of documentation to many places.

The disadvantage of the many-place style is that it is hard to look up 
details.  I may remember seeing somewhere various rules about something, 
but if it isn't clear where to look for it again, I will have trouble 
finding it.

The weakness of the one-place style is that it isn't always easy to find 
that one place.  R documentation especially suffers from this, because 
it is hard to find things in the manuals if you're looking in the help() 
system.  I think the solution is to make it easier to find things in the 
manuals, rather than repeating bits and pieces of the manuals all across 
the help system.

One way to do this is to link the manuals into the help system, and I 
did some work on this last year, but unfortunately this requires a newer 
version of Texinfo than we are allowed to use because of FSF license 
restrictions.

Duncan Murdoch



On 16/11/2009 9:09 PM, Steven McKinney wrote:
>> -----Original Message-----
>> From: Gabor Grothendieck [mailto:ggrothendieck at gmail.com]
>> Sent: Monday, November 16, 2009 4:52 PM
>> To: Duncan Murdoch
>> Cc: Steven McKinney; R Help
>> Subject: Re: [R] Where are usages like "== 2L" documented?
>>
>> On Mon, Nov 16, 2009 at 7:25 PM, Duncan Murdoch <murdoch at stats.uwo.ca>
>> wrote:
>>> On 16/11/2009 6:47 PM, Steven McKinney wrote:
>>>> ?NumericConstants
>>>>
>>>> will bring up a help page that mentions
>>>> "All other numeric constants start with a digit or period and are
>> either a
>>>> decimal or hexadecimal constant optionally followed by L."
>>>>
>>>> and
>>>>
>>>> "An numeric constant immediately followed by L is regarded as an
>> integer
>>>> number when possible (and with a warning if it contains a "."). "
> 
> The word "integer" in the above sentence of the NumericConstants help
> page is hyperlinked to the integer() function page.  There is then no
> example or discussion of L there.
> 
>>>> but I haven't found discussion of it anywhere else in the help
>> pages.
>>>> Others may know what other help pages discuss this.
>>>>
>>>> I'm surprised that the help page invoked from
>>>> ?integer
>>>> does not discuss this.  Anyone know why not?
>>> This is part of the syntax of the language.  It has nothing to do
>> with the
>>> integer() function, which is what ?integer is asking about.
>> It might be useful to have a SeeAlso to NumericConstants on that help
>> page for those who looked up ?integer thinking it might be about
>> integer constants.
> 
> Yes, additional discussion of "L" would be very valuable.  I've had
> several people ask me about usages, as this original poster did.
> I think that increased use of L has outpaced updating of help entries.
> Given that L is appearing in more places, I'd like to request additional
> discussion of it and examples using it in help pages.
> 
>> class(1L)
> [1] "integer"
>> storage.mode(1L)
> [1] "integer"
> 
> Since "integer" is the term often associated with this language construct,
> that seems a natural place to say something about it, and direct users
> to other appropriate help pages.
> 
> The help page for storage.mode() shows an example with "1i" in it,
> could "1L" please also be added?  ("1.0" or "1." would also be useful.)
> 
> cex3 <- c("NULL","1","1:1","1i","list(1)","data.frame(x=1)",
>   "pairlist(pi)", "c", "lm", "formals(lm)[[1]]",  "formals(lm)[[2]]",
>   "y~x","expression((1))[[1]]", "(y~x)[[1]]",
>   "expression(x <- pi)[[1]][[1]]")
> 
> 
> The "L" language construct is often used in length checks such as
> in the sample() function " if (length(x) == 1L ..."
> 
> The length() function help page discusses
> " The default method currently returns an integer of length 1."
> again with the "integer" hyperlinked to the integer() help page.
> Since length() therefore can only assess integer lengths
> from 0 to about 2^31 - 1 it would be helpful to discuss this
> integer "L" construct and the range of values that can be expressed
> with mode "integer" more fully somewhere in one of these help topics.
> 
> 
>> sample
> function (x, size, replace = FALSE, prob = NULL) 
> {
>     if (length(x) == 1L && is.numeric(x) && x >= 1) {
>         if (missing(size)) 
>             size <- x
>         .Internal(sample(x, size, replace, prob))
>     }
>     else {
>         if (missing(size)) 
>             size <- length(x)
>         x[.Internal(sample(length(x), size, replace, prob))]
>     }
> }
> <environment: namespace:base>
> 
> 
> Best
> Steve McKinney
> 
> ______________________________________________
> R-help at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-help
> PLEASE do read the posting guide http://www.R-project.org/posting-guide.html
> and provide commented, minimal, self-contained, reproducible code.




More information about the R-help mailing list