language: Explain that with does not shadow

Until now, both `with` and `inherit` used the wording
"adds variables to the scope".

But that adding happens in very different ways:
`inherit` shadows, `with` does not.

This is confusing, compare:

    let
      a = "outer";
      attrs = { a = "inner"; b = 3; };
    in
      (with attrs; rec { res = [a b]; }).res

Result: `[ "outer" 3 ]`

    let
      a = "outer";
      attrs = { a = "inner"; b = 3; };
    in
      (rec { inherit (attrs) a b; res = [a b]; }).res

Result: `[ "inner" 3 ]`

This causes common packaging errors, such as:

    myOverlay = {
      
      zxing-cpp = callPackage ...; # the C++ package

      myPythonWithPackages = python.withPackages (ps: with ps; [
        numpy
        ...
        zxing-cpp  # Wrong:
                   # Incorrectly refers to the C++ package, not `ps.zxing-cpp`!
                   # Thus `import zxingcpp` fails at runtime.

Thus, the explicit warning.

doc/manual/src/language/index.md

@@ -434,7 +434,19 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   Add all attributes from the given set to the scope (evaluates to `1`)
+   Add all attributes from the given set to the scope (evaluates to `1`).
+
+   **Warning:**
+   In contrast to `inherit`, does not shadow existing variables with the same name!
+   Existing outer variables get precedence over variables coming from `with`. Example:
+   ```
+   let
+     a = "outer";
+     attrs = { a = "inner"; b = 3; };
+   in
+     with attrs; [ a b ]
+   ```
+   Evaluates to `[ "outer" 3 ]`.
 
   </td>
  </tr>
@@ -447,6 +459,7 @@ This is an incomplete overview of language features, by example.
   <td>
 
    Adds the variables to the current scope (attribute set or `let` binding).
+   Shadows existing variables with the same name.
    Desugars to `pkgs = pkgs; src = src;`
 
   </td>
@@ -460,6 +473,7 @@ This is an incomplete overview of language features, by example.
   <td>
 
    Adds the attributes, from the attribute set in parentheses, to the current scope (attribute set or `let` binding).
+   Shadows existing variables with the same name.
    Desugars to `lib = pkgs.lib; stdenv = pkgs.stdenv;`
 
   </td>