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.