R devel - Dec 2023 - Request: documenting more specifically language objects in the R Language Definition document

Dear  all,


This is a request to get language objects more documented in the R Language
Definition document (CRAN
version<https://cran.r-project.org/doc/manuals/r-release/R-lang.html>,
ETHZ R-devel
version<https://stat.ethz.ch/R-manual/R-devel/doc/manual/R-lang.html>).

Section '2.1.3 Language objects' claims
There are three types of objects that constitute the R language. They are calls,
expressions, and names.
But then there is only a subsection '2.1.3.1 Symbol objects' which, if I
do not understand wrongly, correspond to names subtype of language objects. It
would be great if calls and expressions subtypes were specified with more detail
as well. And also calls subtype 'formula'.

I came to here since when looking help for formula, it documents the stats
function formula -Model Formula-, and it just says that it produces an object of
class '"formula"' [...] and that a formula object has an
associated environment [...]. Maybe this, and saying  that the mode of a formula
is a call it is enough to describe a formula?

Same section 2.1.3 also claims

They can be [...] converted to and from lists by the as.list and as.call
functions

It could be added also a description of how these lists should be (structured,
their components, names, etc.) for the different language objects, that is, for
names, expressions, calls, formulas and so on.

Thank you.

Best wishes,
Iago




	[[alternative HTML version deleted]]

I doubt if anyone will take you up on this request.  Only R Core members 
can change those manuals, and it's hard work to write clear and correct 
documentation.  This probably won't make it high enough on their lists 
of priorities to actually be addressed.

What you could do is try to write it yourself.  Find some helpers who 
really know the details (not necessarily R Core members) to review your 
proposal.  Once you have it written and everyone agrees it is correct, 
either publish it as a blog entry somewhere, or submit it to R Core for 
inclusion in the manual.  I don't recommend posting early drafts to this 
mailing list, though you could post near-final ones here:  you're only 
going to get a few comments before people lose interest.

This would be a lot of work for you.  Besides the work of writing 
clearly and correctly, you need to learn the material.  But that's a big 
benefit for you if you are really interested in working with this kind 
of thing.

Duncan Murdoch

On 13/12/2023 4:19 a.m., Iago Gin? V?zquez wrote:
> Dear  all,
> 
> 
> This is a request to get language objects more documented in the R Language
Definition document (CRAN
version<https://cran.r-project.org/doc/manuals/r-release/R-lang.html>,
ETHZ R-devel
version<https://stat.ethz.ch/R-manual/R-devel/doc/manual/R-lang.html>).
> 
> Section '2.1.3 Language objects' claims
> There are three types of objects that constitute the R language. They are
calls, expressions, and names.
> But then there is only a subsection '2.1.3.1 Symbol objects' which,
if I do not understand wrongly, correspond to names subtype of language objects.
It would be great if calls and expressions subtypes were specified with more
detail as well. And also calls subtype 'formula'.
> 
> I came to here since when looking help for formula, it documents the stats
function formula -Model Formula-, and it just says that it produces an object of
class '"formula"' [...] and that a formula object has an
associated environment [...]. Maybe this, and saying  that the mode of a formula
is a call it is enough to describe a formula?
> 
> Same section 2.1.3 also claims
> 
> They can be [...] converted to and from lists by the as.list and as.call
functions
> 
> It could be added also a description of how these lists should be
(structured, their components, names, etc.) for the different language objects,
that is, for names, expressions, calls, formulas and so on.
> 
> Thank you.
> 
> Best wishes,
> Iago
> 
> 
> 
> 
> 	[[alternative HTML version deleted]]
> 
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel