extend env vignette for common trap, closes #6031

Author: jangorecki

vignettes/datatable-programming.Rmd

@@ -376,6 +376,19 @@ print(j)
 DT[, j, env = list(j = j)]
 ```
 
+### Common mistakes
+
+It is important to understand the difference between passing an object and a name that points to an object. See the verbose output of following examples.
+
+```{r obj_vs_objname}
+DT[, fun(Petal.Width), env = list(fun = mean), verbose=TRUE]
+DT[, fun(Petal.Width), env = list(fun = "mean"), verbose=TRUE]
+```
+
+User will usually want to substitute function name rather than function body.
+
+In case of any doubts on the `env` interface functioning user is advised to look at `verbose` output.
+
 ## Retired interfaces
 
 In `[.data.table`, it is also possible to use other mechanisms for variable substitution or for passing quoted expressions. These include `get` and `mget` for inline injection of variables by providing their names as strings, and `eval` that tells `[.data.table` that the expression we passed into an argument is a quoted expression and that it should be handled differently. Those interfaces should now be considered retired and we recommend using the new `env` argument, instead.