From e3a5b4c7234972ed2aca2cb4195c42f13da4fc1b Mon Sep 17 00:00:00 2001
From: Jordi Boggiano <j.boggiano@seld.be>
Date: Thu, 29 Sep 2016 08:20:23 +0200
Subject: [PATCH] Wording tweaks, refs #5733

---
 doc/04-schema.md | 31 +++++++++++++------------------
 1 file changed, 13 insertions(+), 18 deletions(-)

diff --git a/doc/04-schema.md b/doc/04-schema.md
index dc3ab8cdf..ce031493b 100644
--- a/doc/04-schema.md
+++ b/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
-is not strictly required by your project but may improve its performance/functionality
-it is recommended to list such PHP extension in `suggest`.
+and PHP extensions your project needs to run successfully.
 
 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,
-> especially when your project targeted at wider audience. Not all PHP
-> installations are created equal: some may miss extensions you may consider
-> as standard (such as `ext-mysqli` which is not installed by default in
-> Fedora/CentOS minimal installation systems). Failure to list used PHP
-> extension may lead to bad user experience: composer will install your
-> project without any errors just for your project to fail at run-time.
-> `composer show --platform` command lists all PHP extensions available on
-> your system. You may use it to help you to compile the list of extensions to
-> be included in composer.json. Alternatively you may use third party tools
-> to analyze your project for the list of extensions used.
+> **Note:** It is important to list PHP extensions your project requires.
+> Not all PHP installations are created equal: some may miss extensions you
+> may consider as standard (such as `ext-mysqli` which is not installed by
+> default in Fedora/CentOS minimal installation systems). Failure to list
+> required PHP extensions may lead to a bad user experience: Composer will
+> install your package without any errors but it will then fail at run-time.
+> The `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
+> use and require. Alternatively you may use third party tools 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"
     }
 }
 ```