[Rd] Documentation bug?

[GILLIBERT, Andre]

Dead R developers,

In R-devel  2023-02-11 and older R versions, there is a note in the "lm {stats}" help page specifying that:
> Offsets specified by offset will not be included in predictions by predict.lm<http://127.0.0.1:12534/library/stats/help/predict.lm>, whereas those specified by an offset term in the formula will be.

However, the source code as well as basic tests seem to show that both types of offset terms are always used in predictions.
a<-data.frame(off=1:4, outcome=4:1)
mod<-lm(data=a, outcome~1, offset=off)
coef(a) # intercept is zero
predict(mod) # returns 1:4, which uses offset
predict(mod, newdata=data.frame(off=c(3,2,5))) # returns c(3,2,5) which uses the new offset

When looking at the history of R source code, this note seems to exist from R 1.0.0 while the source code of predict.lm already called eval(object$call$offset, newdata)
https://github.com/SurajGupta/r-source/blob/1.0.0/src/library/base/R/lm.R
https://github.com/SurajGupta/r-source/blob/1.0.0/src/library/base/man/lm.Rd

Version 0.99.0 did not contain the note, but already had the call to eval(object$call$offset, newdata)
https://github.com/SurajGupta/r-source/blob/0.99.0/src/library/base/man/lm.Rd
https://github.com/SurajGupta/r-source/blob/0.99.0/src/library/base/R/lm.R

The actual behavior of R seems to be sane to me, but unless I miss something, this looks like a documentation bug.
It seems to have bugged someone before:
https://stackoverflow.com/questions/71264495/why-is-predict-not-ignoring-my-offset-from-a-poisson-model-in-r-no-matter-how-i

Digging deeper in R history, it seems that this note was also found in "glm {stats}" in R 1.0.0 but was removed in R 1.4.1. Maybe somebody forgot to remove it in "lm {stats}" too.

--
Sincerely
Andr� GILLIBERT

	[[alternative HTML version deleted]]