Fix remaining RST conversion artifacts and abbreviations (#8211)

dereuromark · web-flow · commit 1620e4df56b9 · 2026-01-30T19:04:09.000+01:00
* Fix remaining RST conversion artifacts, abbreviations, and double spaces.

- Replace RST escaped underscores \_id with inline code `_id` in
  associations docs (5 instances)
- Replace RST escaped angle brackets \&lt;locale\&gt; with inline code in
  internationalization docs
- Replace RST escaped backticks \` with proper markdown in
  configuration docs
- Replace RST escaped \# with inline code in number docs
- Fix "ie." to "i.e." across number.md and events.md (14 instances)
- Fix "eg." to "e.g." in saving-data.md
- Fix double spaces in html.md and testing.md code comments

* Fix code fencing.
diff --git a/docs/en/appendices/5-0-migration-guide.md b/docs/en/appendices/5-0-migration-guide.md
@@ -259,7 +259,7 @@ The above will disable creation of entity objects and return rows as arrays inst
   tests.
 - Previously, most data validation error messages were simply `The provided value is invalid`.
   Now, the data validation error messages are worded more precisely.
-  For example, `` The provided value must be greater than or equal to \`5\ ``\`.
+  For example, ``The provided value must be greater than or equal to `5`.``
 
 ### View
 
diff --git a/docs/en/console-commands.md b/docs/en/console-commands.md
@@ -13,7 +13,7 @@ generate related files.
 
 The CakePHP Console uses a dispatcher-type system to load commands, parse
 their arguments and invoke the correct command. While the examples below use
-bash the CakePHP console is compatible with any \*nix shell and windows.
+bash the CakePHP console is compatible with any *nix shell and windows.
 
 A CakePHP application contains **src/Command** directory that contain its commands.
 It also comes with an executable in the **bin** directory:
diff --git a/docs/en/console-commands/commands.md b/docs/en/console-commands/commands.md
@@ -80,8 +80,11 @@ After saving this file, you should be able to run the following command:
 
 ``` bash
 bin/cake hello jillian
+```
+
+This outputs:
 
-# Outputs
+```
 Hello jillian
 ```
 
@@ -277,7 +280,9 @@ This will show your description in the Cake CLI:
 
 ``` bash
 bin/cake
+```
 
+```
 App:
   - user
   └─── My custom description
@@ -287,6 +292,9 @@ As well as in the help section of your command:
 
 ``` bash
 cake user --help
+```
+
+```
 My custom description
 
 Usage:
diff --git a/docs/en/console-commands/input-output.md b/docs/en/console-commands/input-output.md
@@ -405,6 +405,6 @@ no styling is done at all. There are three modes you can use.
   This is a good mode to use if you are outputting XML or, want to debug why
   your styling isn't working.
 
-By default, on \*nix systems ConsoleOutput objects default to color output.
+By default, on *nix systems ConsoleOutput objects default to color output.
 On Windows systems, plain output is the default unless the `ANSICON`
 environment variable is present.
diff --git a/docs/en/core-libraries/email.md b/docs/en/core-libraries/email.md
@@ -526,7 +526,7 @@ $mailer->setTransport(new \Cake\Mailer\Transport\DebugTransport());
 > account](https://support.google.com/accounts/answer/6010255).
 
 > [!NOTE]
->   [Gmail SMTP settings](https://support.google.com/a/answer/176600?hl=en).
+> [Gmail SMTP settings](https://support.google.com/a/answer/176600?hl=en).
 
 > [!NOTE]
 > To use SSL + SMTP, you will need to have the SSL configured in your PHP
diff --git a/docs/en/core-libraries/events.md b/docs/en/core-libraries/events.md
@@ -362,7 +362,7 @@ a more direct approach and only listen to the event you really need:
 
 ``` php
 // You can create the following before the
-// save operation, ie. config/bootstrap.php
+// save operation, i.e. config/bootstrap.php
 use Cake\Datasource\FactoryLocator;
 use Cake\Event\EventInterface;
 // If sending emails
diff --git a/docs/en/core-libraries/internationalization-and-localization.md b/docs/en/core-libraries/internationalization-and-localization.md
@@ -58,11 +58,11 @@ grouping of translation messages. When no group is used, then the default group
 is selected.
 
 The core strings messages extracted from the CakePHP library can be stored
-separately in a file named **cake.po** in **resources/locales/**.
+separately in a file named **cake.po** in `resources/locales/`.
 The [CakePHP localized library](https://github.com/cakephp/localized) houses
 translations for the client-facing translated strings in the core (the cake
 domain). To use these files, link or copy them into their expected location:
-**resources/locales/\<locale\>/cake.po**. If your locale is incomplete or incorrect,
+`resources/locales/<locale>/cake.po`. If your locale is incomplete or incorrect,
 please submit a PR in this repository to fix it.
 
 Plugins can also contain translation files, the convention is to use the
diff --git a/docs/en/core-libraries/number.md b/docs/en/core-libraries/number.md
@@ -61,7 +61,7 @@ scheme:
 |------------|-------------------------------------|
 | EUR        | €1.234,56                           |
 | GBP        | £1,234.56                           |
-| USD        | \$1,234.56                          |
+| USD        | $1,234.56                           |
 
 The third parameter is an array of options for further defining the
 output. The following options are available:
@@ -70,13 +70,13 @@ output. The following options are available:
 | ---- | ---- |
 | before | Text to display before the rendered number. |
 | after | Text to display after the rendered number. |
-| zero | The text to use for zero values; can be a string or a number. ie. 0, 'Free!'. |
-| places | Number of decimal places to use, ie. 2 |
-| precision | Maximal number of decimal places to use, ie. 2 |
-| locale | The locale name to use for formatting number, ie. "fr_FR". |
-| fractionSymbol | String to use for fraction numbers, ie. ' cents'. |
+| zero | The text to use for zero values; can be a string or a number. i.e. 0, 'Free!'. |
+| places | Number of decimal places to use, i.e. 2 |
+| precision | Maximal number of decimal places to use, i.e. 2 |
+| locale | The locale name to use for formatting number, i.e. "fr_FR". |
+| fractionSymbol | String to use for fraction numbers, i.e. ' cents'. |
 | fractionPosition | Either 'before' or 'after' to place the fraction symbol. |
-| pattern | An ICU number pattern to use for formatting the number ie. \#,###.00 |
+| pattern | An ICU number pattern to use for formatting the number i.e. `#,###.00` |
 | useIntlCode | Set to `true` to replace the currency symbol with the international currency code. |
 
 If `$currency` value is `null`, the default currency will be retrieved from
@@ -216,10 +216,10 @@ resides.
 
 | Option | Description |
 | ---- | ---- |
-| places | Number of decimal places to use, ie. 2 |
-| precision | Maximum number of decimal places to use, ie. 2 |
-| pattern | An ICU number pattern to use for formatting the number ie. \#,###.00 |
-| locale | The locale name to use for formatting number, ie. "fr_FR". |
+| places | Number of decimal places to use, i.e. 2 |
+| precision | Maximum number of decimal places to use, i.e. 2 |
+| pattern | An ICU number pattern to use for formatting the number i.e. `#,###.00` |
+| locale | The locale name to use for formatting number, i.e. "fr_FR". |
 | before | Text to display before the rendered number. |
 | after | Text to display after the rendered number. |
 
@@ -302,9 +302,9 @@ The `$options` parameter takes the same keys as `Number::format()` itself:
 
 | Option    | Description                                                |
 |-----------|------------------------------------------------------------|
-| places    | Number of decimal places to use, ie. 2                     |
-| precision | Maximum number of decimal places to use, ie. 2             |
-| locale    | The locale name to use for formatting number, ie. "fr_FR". |
+| places    | Number of decimal places to use, i.e. 2                     |
+| precision | Maximum number of decimal places to use, i.e. 2             |
+| locale    | The locale name to use for formatting number, i.e. "fr_FR". |
 | before    | Text to display before the rendered number.                |
 | after     | Text to display after the rendered number.                 |
 
diff --git a/docs/en/development/configuration.md b/docs/en/development/configuration.md
@@ -506,13 +506,13 @@ will not ever overwrite the existing configuration.
 
 Dumps all or some of the data in Configure into a file or storage system
 supported by a config engine. The serialization format is decided by the config
-engine attached as \$config. For example, if the 'default' engine is
+engine attached as `$config`. For example, if the 'default' engine is
 a `Cake\Core\Configure\Engine\PhpConfig`, the generated file will be
 a PHP configuration file loadable by the
 `Cake\Core\Configure\Engine\PhpConfig`
 
 Given that the 'default' engine is an instance of PhpConfig.
-Save all data in Configure to the file \`my_config.php\`:
+Save all data in Configure to the file `my_config.php`:
 
 ``` php
 Configure::dump('my_config', 'default');
diff --git a/docs/en/development/routing.md b/docs/en/development/routing.md
@@ -109,7 +109,9 @@ added your own routes, you can remove the default routes if you don't need them.
 
 <a id="routes-configuration"></a>
 
-## Connecting Routes<span id="connecting-routes"></span>
+<a id="connecting-routes"></a>
+
+## Connecting Routes
 
 To keep your code `DRY` you should use 'routing scopes'. Routing
 scopes not only let you keep your code DRY, they also help Router optimize its
@@ -144,9 +146,9 @@ $routes->connect(
 
 The first parameter is used to tell the router what sort of URL you're trying to
 control. The URL is a normal slash delimited string, but can also contain
-a wildcard (\*) or [Route Elements](#route-elements). Using a wildcard tells the router
+a wildcard (*) or [Route Elements](#route-elements). Using a wildcard tells the router
 that you are willing to accept any additional arguments supplied. Routes without
-a \* only match the exact template pattern supplied.
+a * only match the exact template pattern supplied.
 
 Once you've specified a URL, you use the last two parameters of `connect()` to
 tell CakePHP what to do with a request once it has been matched. The second
@@ -1453,7 +1455,7 @@ array elements.
 
 ### Using `Router::url()`
 
-`Router::url()` allows you to use `routing arrays <routing array>` in
+`Router::url()` allows you to use routing arrays in
 situations where the array elements required are fixed or easily deduced.
 
 It will provide reverse routing when the destination url is well defined:
diff --git a/docs/en/development/testing.md b/docs/en/development/testing.md
@@ -1281,7 +1281,7 @@ $this->assertSession('That article does not exist', 'Flash.flash.0.message');
 // Assert a flash message in the 'flash' key.
 $this->assertFlashMessage('Article deleted', 'flash');
 
-// Assert the second flash message, also  in the 'flash' key.
+// Assert the second flash message, also in the 'flash' key.
 $this->assertFlashMessageAt(1, 'Article really deleted');
 
 // Assert a flash message in the 'auth' key at the first position
diff --git a/docs/en/orm/associations.md b/docs/en/orm/associations.md
@@ -222,7 +222,7 @@ Possible keys for hasOne association arrays include:
   it should be 'Addresses'. The default value is the name of the association.
 - **foreignKey**: The name of the foreign key column in the other table. The
   default value is the underscored, singular name of the current model,
-  suffixed with '\_id' such as 'user_id' in the above example.
+  suffixed with `_id` such as 'user_id' in the above example.
 - **bindingKey**: The name of the column in the current table used to match the
   `foreignKey`. The default value is the primary key of the current table
   such as 'id' of Users in the above example.
@@ -319,7 +319,7 @@ Possible keys for belongsTo association arrays include:
   it should be 'Users'. The default value is the name of the association.
 - **foreignKey**: The name of the foreign key column in the current table. The
   default value is the underscored, singular name of the other model,
-  suffixed with '\_id' such as 'user_id' in the above example.
+  suffixed with `_id` such as 'user_id' in the above example.
 - **bindingKey**: The name of the column in the other table used to match the
   `foreignKey`. The default value is the primary key of the other table
   such as 'id' of Users in the above example.
@@ -438,7 +438,7 @@ Possible keys for hasMany association arrays include:
   it should be 'Comments'. The default value is the name of the association.
 - **foreignKey**: The name of the foreign key column in the other table. The
   default value is the underscored, singular name of the current model,
-  suffixed with '\_id' such as 'article_id' in the above example.
+  suffixed with `_id` such as 'article_id' in the above example.
 - **bindingKey**: The name of the column in the current table used to match the
   `foreignKey`. The default value is the primary key of the current table
   such as 'id' of Articles in the above example.
@@ -585,13 +585,13 @@ Possible keys for belongsToMany association arrays include:
   found on the join table, or list in case of composite foreign keys.
   This is especially handy if you need to define multiple
   belongsToMany relationships. The default value for this key is the
-  underscored, singular name of the current model, suffixed with '\_id'.
+  underscored, singular name of the current model, suffixed with `_id`.
 - **bindingKey**: The name of the column in the current table, that will be used
   for matching the `foreignKey`. Defaults to the primary key.
 - **targetForeignKey**: The name of the foreign key that references the target
   model found on the join model, or list in case of composite foreign keys.
   The default value for this key is the underscored, singular name of
-  the target model, suffixed with '\_id'.
+  the target model, suffixed with `_id`.
 - **conditions**: An array of `find()` compatible conditions. If you have
   conditions on an associated table, you should use a 'through' model, and
   define the necessary belongsTo associations on it. It is recommended to
diff --git a/docs/en/orm/saving-data.md b/docs/en/orm/saving-data.md
@@ -1091,7 +1091,7 @@ $article->setDirty('tags', true);
 Without the call to `setDirty()` the updated tags will not be saved.
 
 Often you'll find yourself wanting to make an association between two existing
-entities, eg. a user coauthoring an article. This is done by using the method
+entities, e.g. a user coauthoring an article. This is done by using the method
 `link()`, like this:
 
 ``` php
diff --git a/docs/en/orm/table-objects.md b/docs/en/orm/table-objects.md
@@ -489,7 +489,9 @@ class ArticlesTable extends Table
 
 <a id="table-locator-usage"></a>
 
-## Using the TableLocator<span id="table-registry-usage"></span>
+<a id="table-registry-usage"></a>
+
+## Using the TableLocator
 
 `class` Cake\\ORM\\**TableLocator**
 
diff --git a/docs/en/tutorials-and-examples/cms/articles-controller.md b/docs/en/tutorials-and-examples/cms/articles-controller.md
@@ -567,7 +567,7 @@ The `ArticlesController` can also be built with `bake`:
 bin/cake bake controller articles
 ```
 
-However, this does not build the **templates/Articles/\*.php** files.
+However, this does not build the **templates/Articles/*.php** files.
 :::
 
 With a basic articles management setup, we'll create the [basic actions
diff --git a/docs/en/views/helpers/html.md b/docs/en/views/helpers/html.md
@@ -160,7 +160,7 @@ echo $this->Html->meta(
     ['type' => 'icon'],
 );
 // Output (line breaks added)
-// Note: The helper code makes two meta tags to  ensure the
+// Note: The helper code makes two meta tags to ensure the
 // icon is downloaded by both newer and older browsers
 // which require different rel attribute values.
 <link
