[Rd] [PATCH] suggestions for R-lang manual
Scott Kostyshak
skostysh at princeton.edu
Thu Nov 21 07:17:50 CET 2013
Attached is a patch with suggestions for the R-lang manual at r64277.
Below are a few comments (some are implemented in the patch):
In the section "Objects", there is a table introduced by "The
following table describes the possible values returned by typeof". One
of the results is "any". Can "any" be returned by "typeof()" ?
Regarding the "Recycling rules" section,
-One exception is that when adding vectors to matrices, a warning is not
-given if the lengths are incompatible.
- at c Is that a bug?
-
was this a bug that was fixed? I see the following behavior:
> myvec <- 1:3
> mymat <- matrix(1:12, ncol=2)
> myvec <- 1:5
> myvec + mymat
[,1] [,2]
[1,] 2 9
[2,] 4 11
[3,] 6 13
[4,] 8 15
[5,] 10 12
[6,] 7 14
Warning message:
In myvec + mymat :
longer object length is not a multiple of shorter object length
>
Regarding
-The arguments in the call to the generic are rematched with the
-arguments for the method using the standard argument matching mechanism.
-The first argument, i.e.@: the object, will have been evaluated.
-
this information is duplicated. See a few paragraphs up "When the
method is invoked it is called..."
Scott
--
Scott Kostyshak
Economics PhD Candidate
Princeton University
-------------- next part --------------
Index: trunk/doc/manual/R-lang.texi
===================================================================
--- trunk/doc/manual/R-lang.texi (revision 64277)
+++ trunk/doc/manual/R-lang.texi (working copy)
@@ -1064,7 +1064,7 @@
@cindex function
@cindex function arguments
Function calls can have @emph{tagged} (or @emph{named}) arguments, as in
- at code{plot(x, y, pch = 3)} arguments without tags are known as
+ at code{plot(x, y, pch = 3)}. Arguments without tags are known as
@emph{positional} since the function must distinguish their meaning from
their sequential positions among the arguments of the call, e.g., that
@code{x} denotes the abscissa variable and @code{y} the ordinate. The
@@ -1308,10 +1308,10 @@
ignored. If @var{value1} has any type other than a logical or a numeric
vector an error is signalled.
-If/else statements can be used to avoid numeric problems such as taking
-the logarithm of a negative number. Because if/else statements are the
-same as other statements you can assign the value of them. The two
-examples below are equivalent.
+ at code{if}/@code{else} statements can be used to avoid numeric problems
+such as taking the logarithm of a negative number. Because
+ at code{if}/@code{else} statements are the same as other statements you
+can assign the value of them. The two examples below are equivalent.
@example
> if( any(x <= 0) ) y <- log(1+x) else y <- log(x)
@@ -1327,7 +1327,7 @@
compound statement wrapped in braces, putting the @code{else} on the
same line as the closing brace that marks the end of the statement.
-If/else statements can be nested.
+ at code{if}/@code{else} statements can be nested.
@example
if ( @var{statement1} ) @{
@@ -1342,7 +1342,7 @@
One of the even numbered statements will be evaluated and the resulting
value returned. If the optional @code{else} clause is omitted and all
-the odd numbered @var{statement}'s evaluate to @code{FALSE} no statement
+the odd numbered @var{statement}s evaluate to @code{FALSE} no statement
will be evaluated and @code{NULL} is returned.
The odd numbered @var{statement}s are evaluated, in order, until one
@@ -1378,7 +1378,7 @@
of the loop (if there is one) is then executed. No statement below
@code{next} in the current loop is evaluated.
-The value returned by a loop statement statement is always @code{NULL}
+The value returned by a loop statement is always @code{NULL}
and is returned invisibly.
@node repeat, while, Looping, Control structures
@@ -1451,7 +1451,7 @@
where the elements of @var{list} may be named. First, @var{statement}
is evaluated and the result, @var{value}, obtained. If @var{value} is a
number between 1 and the length of @var{list} then the corresponding
-element @var{list} is evaluated and the result returned. If @var{value}
+element of @var{list} is evaluated and the result returned. If @var{value}
is too large or too small @code{NULL} is returned.
@example
@@ -1530,10 +1530,6 @@
As from @R{} 1.4.0, any arithmetic operation involving a zero-length
vector has a zero-length result.
-One exception is that when adding vectors to matrices, a warning is not
-given if the lengths are incompatible.
- at c Is that a bug?
-
@node Propagation of names, Dimensional attributes, Recycling rules, Elementary arithmetic operations
@subsection Propagation of names
@cindex name
@@ -1842,7 +1838,7 @@
matching.
The most important example of a class method for @code{[} is that used
-for data frames. It is not be described in detail here (see the help
+for data frames. It is not described in detail here (see the help
page for @code{[.data.frame}, but in broad terms, if two indices are
supplied (even if one is empty) it creates matrix-like indexing for a
structure that is basically a list of vectors of the same length. If a
@@ -1865,7 +1861,7 @@
@example
x[3:5] <- 13:15
@end example
-The result of this commands is as if the following had been executed
+The result of this command is as if the following had been executed
@example
`*tmp*` <- x
x <- "[<-"(`*tmp*`, 3:5, value=13:15)
@@ -2246,7 +2242,7 @@
this is not given a name it is referred to as an
@cindex function, anonymous
anonymous
-function. Anonymous functions are most frequently used as arguments
+function. Anonymous functions are most frequently used as arguments to
other functions such as the @code{apply} family or @code{outer}.
Here is a simple function: @code{echo <- function(x) print(x)}. So
@@ -2455,7 +2451,7 @@
The process of filling the value slot of a promise by
@cindex evaluation
evaluating the
-contents of the expression slot in the promises environment is called
+contents of the expression slot in the promise's environment is called
@emph{forcing} the promise. A promise will only be forced once, the
value slot content being used directly later on.
@@ -2697,10 +2693,10 @@
functions and types that will be discussed elsewhere.
The class system is facilitated through the @code{class} attribute.
-This attribute is a list of class names. So to create an object of
-class @code{"foo"} one simply attaches a class attribute with the string
- at samp{"foo"} in it. Thus, virtually anything can be turned in to an
-object of class @code{"foo"}.
+This attribute is a character vector of class names. So to create an
+object of class @code{"foo"} one simply attaches a class attribute with
+the string @samp{"foo"} in it. Thus, virtually anything can be turned
+in to an object of class @code{"foo"}.
The object system makes use of
@cindex function, generic
@@ -2826,7 +2822,7 @@
existing systems since the user is only responsible for dealing with the
new representation and not with any of the existing representations.
-The bulk of the uses of this methodology are to provided specialized
+The bulk of the uses of this methodology are to provide specialized
printing for objects of different types; there are about 40 methods for
@code{print}.
@@ -2952,10 +2948,6 @@
Any arguments to the generic that were evaluated prior to the call to
@code{UseMethod} remain evaluated.
-The arguments in the call to the generic are rematched with the
-arguments for the method using the standard argument matching mechanism.
-The first argument, i.e.@: the object, will have been evaluated.
-
If the first argument to @code{UseMethod} is not supplied it is assumed
to be the name of the current function. If two arguments are supplied
to @code{UseMethod} then the first is the name of the method and the
@@ -2963,7 +2955,7 @@
evaluated so that the required method can be determined. In this case
the first argument in the call to the generic is not evaluated and is
discarded. There is no way to change the other arguments in the call to
-the method these remain as they were in the call to the generic. This
+the method; these remain as they were in the call to the generic. This
is in contrast to @code{NextMethod} where the arguments in the call to
the next method can be altered.
@@ -3405,7 +3397,7 @@
This looks straightforward, but one will discover that the y label
becomes an ugly @code{c(...)} expression. It happens because the rules
-of lazy evaluation causes the evaluation of the @code{ylab} expression
+of lazy evaluation cause the evaluation of the @code{ylab} expression
to happen @emph{after} @code{y} has been modified. The solution is to
force @code{ylab} to be evaluated first, i.e.,
@@ -3975,7 +3967,7 @@
@section Error options
There are a number of @code{options} variables that can be used to
-control how @R{} handles errors and warnings. The are listed in the
+control how @R{} handles errors and warnings. They are listed in the
table below.
@table @samp
@@ -4414,8 +4406,8 @@
@cindex identifier
Identifiers consist of a sequence of letters, digits, the period
-(@samp{.}) and the underscore. They must not start with a digit nor
-underscore, nor with a period followed by a digit.
+(@samp{.}) and the underscore. They must not start with a digit or
+an underscore, or with a period followed by a digit.
The definition of a letter depends on the current locale: the precise
set of characters allowed is given by the C expression @code{(isalnum(c)
@@ -4542,7 +4534,7 @@
@node Indexing tokens, , Grouping, Tokens
@subsection Indexing tokens
-Indexing of arrays and vectors performed using the single and double
+Indexing of arrays and vectors is performed using the single and double
brackets, @samp{[]} and @samp{[[]]}. Also, indexing tagged lists
may be done using the @samp{$} operator.
@@ -4611,7 +4603,7 @@
@node Infix and prefix operators, Index constructions, Function calls (expressions), Expressions
@subsection Infix and prefix operators
-The order of precedence (highest first) of the operators are
+The order of precedence (highest first) of the operators is
@example
::
@@ -4664,7 +4656,7 @@
Notice that the
@cindex assignment
assignment symbols are operators just like the arithmetic, relational,
-and logical ones. Any expressions is allowed also on the target side of
+and logical ones. Any expression is allowed also on the target side of
an assignment, as far as the parser is concerned (@code{2 + 2 <- 5} is a
valid expression as far as the parser is concerned. The evaluator will
object, though). Similar comments apply to the model formula operator.
More information about the R-devel
mailing list