[Rd] Request: documenting more specifically language objects in the R Language Definition document

[Iago Giné Vázquez]

Thank you for your answers.

Just let me disagree slightly with Tomas view.

On 13/12/2023 12:05, Tomas Kalibera wrote:
> On 12/13/23 11:27, Duncan Murdoch wrote:
>> 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.
>
> There is another aspect of this - portable R packages only use 
> documented behavior of R, relying on that such behavior will not 
> change unless absolutely necessary. A very hard part of 
> writing/expanding the official documentation is deciding on what 
> should and what shouldn't be the stable/documented behavior, and even 
> more so when it is about fundamental things. It is essential that some 
> behavior stays undocumented and is not relied on, otherwise it 
> wouldn't be possible to maintain and improve R.

Actually, I would say that "portable R packages" use a lot these types 
of objects (formulas, calls, ...) and I would bet that they even use 
quite a lot of the undocumented behaviour I would expect to find, which 
is more needed precisely "when it is about fundamental things".


Iago


>
> So if you primarily wanted to get an answer to a specific technical 
> question about say formulas, it is best to just ask that question, 
> rather than asking for expanding the documentation.
>
> Tomas
>
>
>>
>> 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 using r-project.org mailing list
>>> https://stat.ethz.ch/mailman/listinfo/r-devel
>>
>> ______________________________________________
>> R-devel using r-project.org mailing list
>> https://stat.ethz.ch/mailman/listinfo/r-devel
	[[alternative HTML version deleted]]