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. Drupal's docblock and code documentation includes some examples of incorrect usage as well.

Let's start to correct some of that confusion by replacing 'e.g.,' by what it means in English: 'for instance,'. This will require a number of patches until 'e.g.' is appropriately replaced. Based on the first round, the patch size should be around 50k.

Note: Frequently, the replacement of text with 'for instance' or 'for example' requires the re-wrapping of docblocks and code comments to be near but less than 80 characters.

Comments

Lars Toomre created an issue. See original summary.

lars toomre’s picture

lars toomre commented
Related issues: +#2640960: Replace i.e. and e.g. with English words in /core/scripts, /core/tests & /core/themes directories, +#2640966: Some fixes for 'e.g.' in docblocks and code comments - Round 8

Related issues in sequence of rounds:
- #2640960: Replace i.e. and e.g. with English words in /core/scripts, /core/tests & /core/themes directories
- #2640966: Some fixes for 'e.g.' in docblocks and code comments - Round 8

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

I know you like to fix up other problems at the same time... but in the last few of these patches I've reviewed, I could have marked the patch RTBC if not for some fixes to other stuff that weren't quite right. So maybe consider just doing "e.g." in the "e.g." patches, and not venturing into adding missing return/param docs, fixing up other problems, etc.?

Also please do not include translatable strings in the patches. We can't commit changes to translatable strings to every version of Drupal, and also just because we don't like "e.g." very much is not a great reason to invalidate 160+ translations of that string on localize.drupal.org.

Thanks!

lars toomre’s picture

lars toomre commented
Related issues: +#2645178: Fix 'e.g.' and 'i.e.' usage in user-facing strings

Added #2645178: Fix 'e.g.' and 'i.e.' usage in user-facing strings as a holding area for the user-facing string changes.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

Also... As per discussion on that other issue... We need to limit the scope of this issue to only e.g. and i.e. fixes.

Version: 8.0.x-dev » 8.1.x-dev

Drupal 8.0.6 was released on April 6 and is the final bugfix release for the Drupal 8.0.x series. Drupal 8.0.x will not receive any further development aside from security fixes. Drupal 8.1.0-rc1 is now available and sites should prepare to update to 8.1.0.

Bug reports should be targeted against the 8.1.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.2.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented
Status: Active » Closed (won't fix)

This series of issues is badly scoped. I am just going to close them. Sorry.