[Rd] Request: documenting more specifically language objects in the R Language Definition document
Iago Giné Vázquez
|@go@g|ne @end|ng |rom @jd@e@
Wed Dec 13 13:31:17 CET 2023
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]]
More information about the R-devel
mailing list