Wording tweaks, refs #5733

doc/04-schema.md

@@ -328,9 +328,7 @@ a constraint that it otherwise would not. For more information [see the
 aliases article](articles/aliases.md).
 
 `require` and `require-dev` also support references to specific PHP versions
-and PHP extensions your project needs to run successfully. If PHP extension
+and PHP extensions your project needs to run successfully.
-is not strictly required by your project but may improve its performance/functionality
-it is recommended to list such PHP extension in `suggest`.
 
 Example:
 
@@ -339,24 +337,20 @@ Example:
     "require" : {
         "php" : "^5.5 || ^7.0",
         "ext-mbstring": "*"
-    },
-    "suggest" : {
-        "ext-XCache": "Opcode cache to improve performance"
     }
 }
 ```
 
-> **Note:** It is important to list PHP extensions your project uses,
+> **Note:** It is important to list PHP extensions your project requires.
-> especially when your project targeted at wider audience. Not all PHP
+> Not all PHP installations are created equal: some may miss extensions you
-> installations are created equal: some may miss extensions you may consider
+> may consider as standard (such as `ext-mysqli` which is not installed by
-> as standard (such as `ext-mysqli` which is not installed by default in
+> default in Fedora/CentOS minimal installation systems). Failure to list
-> Fedora/CentOS minimal installation systems). Failure to list used PHP
+> required PHP extensions may lead to a bad user experience: Composer will
-> extension may lead to bad user experience: composer will install your
+> install your package without any errors but it will then fail at run-time.
-> project without any errors just for your project to fail at run-time.
+> The `composer show --platform` command lists all PHP extensions available on
-> `composer show --platform` command lists all PHP extensions available on
+> your system. You may use it to help you compile the list of extensions you
-> your system. You may use it to help you to compile the list of extensions to
+> use and require. Alternatively you may use third party tools to analyze
-> be included in composer.json. Alternatively you may use third party tools
+> your project for the list of extensions used.
-> to analyze your project for the list of extensions used.
 
 
 #### require
@@ -421,7 +415,8 @@ Example:
 ```json
 {
     "suggest": {
-        "monolog/monolog": "Allows more advanced logging of the application flow"
+        "monolog/monolog": "Allows more advanced logging of the application flow",
+        "ext-xml": "Needed to support XML format in class Foo"
     }
 }
 ```