fewer words, easier reading

incorporating feedback

incorporating feedback

applying fixes

site/docs/skylark/language.md

@@ -31,7 +31,7 @@ def fizz_buzz(n):
 fizz_buzz(20)
 ```
 
-Starlark's semantics can differ from Python, and behavioral differences are
+Starlark's semantics can differ from Python, but behavioral differences are
 rare, except for cases where Starlark raises an error. The following Python
 types are supported:
 
@@ -72,7 +72,7 @@ context. When `fct()` runs, it does so within the context of `foo.bzl`. After
 evaluation for `foo.bzl` completes, the environment contains an immutable entry,
 `var`, with the value `[5]`.
 
-When another, `bar.bzl` loads symbols from `foo.bzl`, loaded values remain
+When another `bar.bzl` loads symbols from `foo.bzl`, loaded values remain
 immutable. For this reason, the following code in `bar.bzl` is illegal:
 
 ```python
@@ -84,8 +84,8 @@ var.append(6)  # runtime error, the list stored in var is frozen
 fct()          # runtime error, fct() attempts to modify a frozen list
 ```
 
-Just like the above example using `bzl` files, values returned by rules are
-immutable too.
+Global variables defined in `bzl` files and cannot be changed outside of the `bzl` file that defined them. Just like the above example using `bzl` files, values returned by rules are
+immutable.
 
 ## Differences between BUILD and .bzl files
 
@@ -105,10 +105,9 @@ illegal, and 2) `*args` and `**kwargs` arguments are not allowed.
 * Global variables are immutable.
 
 * `for` statements are not allowed at the top-level. Use them within functions
-  instead. In BUILD files, you may use list comprehensions.
+  instead. In BUILD files, you may use list comprehensions. That said, we prefer that you use macros, because we think they are easier to read.
 
-* `if` statements are not allowed at the top-level. However, `if` expressions
-  can be used: `first = data[0] if len(data) > 0 else None`.
+* `if` statements are not allowed at the top-level. However, `if` expressions can be used: `first = data[0] if len(data) > 0 else None`.
 
 * Deterministic order for iterating through Dictionaries.
 
@@ -125,12 +124,10 @@ not defined across value types. In short: `5 < 'foo'` will throw an error and
 * In tuples, a trailing comma is valid only when the tuple is between
   parentheses, e.g. write `(1,)` instead of `1,`.
 
-* Dictionary literals cannot have duplicated keys. For example, this is an
-  error: `{"a": 4, "b": 7, "a": 1}`.
+* Dictionary literals cannot have duplicated keys. For example, this is an error: `{"a": 4, "b": 7, "a": 1}`.
 
-* The variable used in a comprehension may not be used after the comprehension.
-  This is stricter than Python 2 and Python 3, which have different behavior
-  (shadowing vs reassignment).
+* The identifier used in a comprehension may not be used after the comprehension.
+  This is stricter than Python 2 and Python 3.
 
 * Strings are represented with double-quotes (e.g. when you call
   [repr](lib/globals.html#repr)).