Re: [Rd] Section 7.1 HML documentation (PR#8484)
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. __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] Section 7.1 HML documentation (PR#8484)
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. __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] Section 7.1 HML documentation (PR#8484)
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 ... = > Hin-Tak Leung wrote: > >> [EMAIL PROTECTED] 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@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] Section 7.1 HML documentation (PR#8484)
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. 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?" Hin-Tak Leung wrote: > [EMAIL PROTECTED] 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@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] Section 7.1 HML documentation (PR#8484)
[EMAIL PROTECTED] 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@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
