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

2023-12-13 Thread 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, 
>>> ETHZ R-devel 
>>> version).
>>>
>>> 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@r-project.org mailing list
>>> https://stat.ethz.ch/mailman/listinfo/r-devel
>>
>> __
>> R-devel@r-project.org mailing list
>> https://stat.ethz.ch/mailman/listinfo/r-devel
[[alternative HTML version deleted]]

__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

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

2023-12-13 Thread Tomas Kalibera 

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.


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, 
ETHZ R-devel 
version).


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@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel


__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel


__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

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

2023-12-13 Thread Duncan Murdoch 
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, 
ETHZ R-devel version).

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@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel


__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

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

2023-12-13 Thread Iago Giné Vázquez 
Dear  all,


This is a request to get language objects more documented in the R Language 
Definition document (CRAN 
version, ETHZ 
R-devel version).

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@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel