R devel - Jan 2006 - Section 7.1 HML documentation (PR#8484)

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 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?

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

Well, you make two very strong assumptions.

First, that your readers start in the beginning and read to the
end.
Second, that your readers are sufficiently dedicated to learn
your terminology.

The first is false:  I got to that page via Google.
The second is only true in varying degrees,
and I wouldn't depend on it too strongly.

When writing documentation, you really have to write for
the case of someone who has a specific problem and wants
to understand that problem as quickly as possible.
That means the manuals should have "local support" --
most of what you need to know should be in one place, and
everything else should be referenced or hyperlinked.

Speaking almost professionally (since I'm almost a linguist),
the word "instead" is normally used in the form "instead of
X",
and you can only delete the "of X" when X is clear and obvious.

For instance, one wouldn't just write

"I go to work instead."

because your readers won't know the
alternative to work.
Likewise, with "earlier":  the underlying form is
"earlier than Y", and you can only delete "than Y" when your
readers are quite clear what you are comparing to.

That's what I meant by "dangling": that X and Y were not clear.

Hin-Tak Leung wrote:
> 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)".
Yep.

> 
>> 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!
That may be so, but it is irrelevant.   The object of this
exercise is not to assign blame, but to make the software
more useful for the next user.

Consequently, you might want to fix it (even if it is my fault),
so long as it is likely to help the next guy (even if it is his fault).
And, I contend that a lot more people Google into the middle
of the documentation than read it from beginning to end.  QED.