[Rd] Section 7.1 HML documentation (PR#8484)

[Hin-Tak Leung]

Greg Kochanski wrote:
> Well, I don't know how it can be precise
> and correct when it has dangling antecedents.
> Gramatically speaking, that's the equivalent of
> an uninitialized pointer.

I don't think there is anything "dangling" there. What the paragraph 
assumes (and quite patently wrongly) is that the reader had encountered 
the concept of "R connection object of the socket type" elsewhere. 
Without that background, one tends to interprete the phrase "socket
connection" in the traditional unix sense (i.e. = "BSD socket"), and
hence one reads the paragraph as " XXX is older than XXX and XXX is
newer than XXX and there had been potential problems with XXX and
one should use XXX instead (of XXX)".

> However, I agree with you that it probably just
> needs a minor bit of fiddling to make sure it
> answers "Instead of what?" and "Earlier than what?"

I have re-read R-data and it seems the fault is yours. Because 
"Connection" is mentioned in quite a major way and is the entire subject
of chapter 6 and comes earlier than the paragraph you quoted in
chapter 7. So it seems to be your own fault of trying to
understand chapter 7 without noticing the header of chapter 6
nor reading it!

===============
6 Connections

"Connections" are used in R in the sense of Chambers (1998), a set of 
functions to replace the use
of file names by a flexible interface to file-like objects.

...

6.1 Types of connections

...
Sockets can also be used as connections via function socketConnection on 
platforms which
support Berkeley-like sockets (most Unix systems, Linux and Windows). 
Sockets can be written
to or read from, and both client and server sockets can be used.
...

7 Network interfaces
Some limited facilities are available to exchange data at a lower level 
across network connections.

7.1 Reading from sockets

...<the paragraph concerned>
=====================



> Hin-Tak Leung wrote:
> 
>> greg.kochanski at phon.ox.ac.uk wrote:
>>
>>> Full_Name: Greg Kochanski
>>> Version: 2.2.0
>>> OS: Debian Linux i686
>>> Submission from: (NULL) (212.159.16.190)
>>>
>>>
>>> In /usr/share/doc/r-doc-html/manual/R-data.html (at least that's where
>>> it is on Debian...) the documentation is unclear.   Comments below.
>>
>>
>>
>> The documentation is, I believe, correct and precise as it stands.
>> What it doesn't emphasize and mention is the difference between
>> "BSD socket" and "socket connection", or an "R connection of the 
>> socket type". And it is recommended that you
>> use "socket connection" instead of "BSD socket".
>>
>> The earlier "BSD socket" is created, read, write with 
>> "make.socket"/"read.socket"/"write socket"/"close socket".
>>
>> The newer "socket connection" is created by creating a new connection 
>> object like this:
>>      con <- socketConnection(port = 79, blocking = TRUE)
>> and invoking the open/write/read method of the "connection"
>> object. type "?connection" in an R prompt for details.
>>
>> "BSD socket" is a unix concept, "socket connection" is an R object.
>> The paragraph should have put "BSD socket" and "socket connection"
>> in quote or italics. Make more sense?
>>
>> Somebody please fix the paragraph... :-).
>>
>>> The paragraph has unclear references, and I have no idea what
>>> it actually means.
>>>
>>>
>>>>> Base R comes with some facilities to communicate via BSD sockets on 
>>>>> systems
>>>
>>>
>>>
>>> that support them (...). One potential problem....
>>>
>>>>> For new projects it is suggested that socket connections are used 
>>>>> instead.
>>>
>>>
>>>
>>>
>>> "Used instead"?   Instead of what?
>>>
>>>
>>>>> The earlier low-level interface is given by functions make.socket,
>>>
>>>
>>>
>>> read.socket, write.socket and close.socket.
>>> What does "earlier" mean?   Earlier than what?
>>>
>>> ______________________________________________
>>> R-devel at r-project.org mailing list
>>> https://stat.ethz.ch/mailman/listinfo/r-devel
>>
>>
>>
>>
>>