Update conditional-compilation.md #1402
Conversation
klu235
commented
Sep 18, 2023
klu235
commented
- Clarify
- Reduce redundancy
src/conditional-compilation.md
Outdated
| on a configuration predicate. | ||
|
|
||
| It is written as `cfg`, `(`, a configuration predicate, and finally `)`. | ||
| on the given configuration predicate (_ConfigurationPredicate_ in the syntax above). |
There was a problem hiding this comment.
The original is written intentionally that way, since we agreed on a style of describing the syntax in prose in most cases, and to not defer to the grammar. Can this change be reverted?
src/conditional-compilation.md
Outdated
| if at least one predicate is true. If there are no predicates, it is false. | ||
| * `not()` with a configuration predicate. It is true if its predicate is false | ||
| and false if its predicate is true. | ||
| * `all()` with a comma-separated list of configuration predicates. It is true precisely if all of the given predicates are true. |
There was a problem hiding this comment.
This doesn't seem to be quite correct, since it doesn't seem to cover the empty list case (there are no true predicates in that case). Perhaps something like:
| * `all()` with a comma-separated list of configuration predicates. It is true precisely if all of the given predicates are true. | |
| * `all()` with a comma-separated list of configuration predicates. It is true if all of the given predicates are true, or if the list is empty. |
src/conditional-compilation.md
Outdated
| * `not()` with a configuration predicate. It is true if its predicate is false | ||
| and false if its predicate is true. | ||
| * `all()` with a comma-separated list of configuration predicates. It is true precisely if all of the given predicates are true. | ||
| * `any()` with a comma-separated list of configuration predicates. It is true precisely if at least one of the given predicates is true. |
There was a problem hiding this comment.
Similarly:
| * `any()` with a comma-separated list of configuration predicates. It is true precisely if at least one of the given predicates is true. | |
| * `any()` with a comma-separated list of configuration predicates. It is true precisely if at least one of the given predicates is true. If there are no predicates, it is false. |
src/conditional-compilation.md
Outdated
| and false if its predicate is true. | ||
| * `all()` with a comma-separated list of configuration predicates. It is true precisely if all of the given predicates are true. | ||
| * `any()` with a comma-separated list of configuration predicates. It is true precisely if at least one of the given predicates is true. | ||
| * `not()` with a configuration predicate. It is true precisely if the given predicate is false. |
There was a problem hiding this comment.
I don't feel like brevity of words here is helping. The original seemed sufficiently brief, and seemed a little clearer to me. I would suggest keeping this as it was before.
| * `not()` with a configuration predicate. It is true precisely if the given predicate is false. | |
| * * `not()` with a configuration predicate. It is true if its predicate is false | |
| and false if its predicate is true. |
src/conditional-compilation.md
Outdated
| _Configuration options_ are either names or key-value pairs, and are either set or | ||
| unset. Configuration options that are names, such as `unix`, are specified by simply writing them. | ||
| Configuration options that are key-value pairs are written in the form `key = "value"`, such as `target_arch = "x86_64"`. |
There was a problem hiding this comment.
The change here seems to remove some explicitness about the details of the format. That is, the words "written as a single identifier" and "Key-value pairs are written as an identifier, =, and then a string.". The text needs to explicitly say what is the syntax and form. Just mentioning an example like key = "value" isn't sufficient to define what the syntax is.
* Clarify * Reduce redundancy
This reverts some of the changes since they were done intentionally, and tries to improve the clarity in other areas.
