The proper use of 'e.g.' and 'i.e.' are confusing and reportedly are one of the most frequent sources of mistakes editors see in technical writing/documentation. Find the patch attached.
| Comment | File | Size | Author |
|---|---|---|---|
| #9 | 2747837-9--remove_ie_eg.patch | 36.07 KB | drunken monkey |
Comments
Comment #2
rajeshwari10 commentedComment #3
borisson_Can you please make sure that these changes don't break the 80 chars rule?
Comment #4
rajeshwari10 commentedI have made changes. So,that the doc wont break 80 chars rule.
Please Review.
Thanks!!
Comment #5
borisson_The 80 cols rule also applies for punctuation. Also please provide an interdiff: https://www.drupal.org/documentation/git/interdiff
80 cols.
80 cols
80 cols
This is wrong now, I think it should be "for, for example, ". But I'm not sure about the second comma.
80 cols
80 cols.
80 cols.
80 cols.
Comment #6
rajeshwari10 commentedAdding patch and interdiff.
Thanks!!
Comment #7
drunken monkeyThanks for creating this issue!
The second line should be indented with two (additional) spaces.
I also wouldn't think we should keep all those commas – in most cases they aren't needed after "for example", I'd say.
Also, the patch has become outdated and would need to be re-rolled.
"Would" because, more importantly, I'm really not sure we need to do this. While a small matter, it still makes the docs more verbose, using the abbreviations is just handier. And I'd hope this wouldn't be such an impediment to proper understanding of the docs. Even if they are regularly misused, I think reading them is far less error-prone, since you can almost always deduce their meaning from the context.
Nevertheless, I've opened #2760911: Use of "e.g." and "i.e." to discuss this on the coding standards level – if the majority there agrees that this is a problem (no matter whether it actually makes it into the standards), we can still do this. But otherwise, I'd be against it.
Comment #8
drunken monkeyComment #9
drunken monkey"The majority" in this case is just Jennifer Hodgdon, but since I respect her opinion on this, let's do this! (Especially since some of the usage is not just code comments, but user-facing.) We should then also try to not use this anymore in new code we introduce – I hope I manage to think of that.
The attached patch is a re-roll applying to the latest dev version and also re-phrasing a few places according to my (personal) taste. It also fixes a few minor problems next to existing changes.
Please review to see if that covers everything!
Side note:
I love this line! It shouts, "I wish I was coding Haskell!"
Comment #10
borisson_Comment #12
drunken monkeyThanks for reviewing!
Committed.
Thanks again for this initiative, rajeshwari10!