1. §3.1 "Some primary expressions contain enclosed expressions." This seems like a weak attempt to provide justification for putting enclosed expressions here, where they don't really belong. I would put them in a level-3 subsection literals and variable references and other primaries.

2. §3.1.5.3 Function coercion: "The function conversion rules result in applying function coercion to $f, wrapping $f in a new function ($p) with the signature function(xs:string) as xs:boolean." Does the new function have a name? What does function-name($p) return? Does this depend on whether coercion to the required type was actually necessary?

3. §3.1.5.3 Function coercion, section on maps: "When the fn:filter() function is called, the following occurs to the function" What means the phrase "to the function"?

4. Same section, the map example in its explanation has 3 occurrences of "query" that should be "expression".

5. §3.1.7 " [Definition: An anonymous function is a function created by an inline function expression.]" I suggest:  [Definition: An anonymous function is a function with no name. Anonymous functions may be created, for example, by evaluating an inline function expression or by partial function application.]

6. §3.2, just before 3.2.1, "Dynamic function ^ are described in 3.2.2 Dynamic Function Call." Insert "calls".

7. §3.2.1 "[Definition: A predicate whose predicate expression returns a numeric type is called a numeric predicate.]" Expressions do not return types. Are we talking of the static type here? Surely not. If it's the dynamic type, as it must be, then being "numeric" is not a property of the predicate, but of a particular evaluation of the predicate. Fortunately the term "numeric predicate" is never used so we can delete the troublesome definition.

8. §3.2.2 Dynamic Function Call. Headings describing syntactic constructs are generally plural: dynamic function calls.

9. §3.3.1 "Relative path expressions are binary operators on step expressions, which are named E1 and E2 in this section.". No, expressions are not operators. Furthermore, a RelativePathExpr can clearly contain more than two operands, and we said earlier that "A path expression consists of a series of one or more steps". Suggest (a) adding to the previous section a para:

A path expression that starts with "/" or "//" selects nodes starting from the root of the tree containing the context item; it is often referred to as an *absolute path expression*.

Then (b) replacing the first two paras of §3.3.1 with:

A relative path expression is a path expression that selects nodes within a tree by following a series of steps starting at the context node (which, unlike an absolute path expression, may be any node in a tree). 

Each non-initial occurrence of "//" in a path expression is expanded as described in 3.3.5 Abbreviated Syntax, leaving a sequence of steps separated by "/". This sequence of steps is then evaluated from left to right. So a path such as E1/E2/E3/E4 is evaluated as ((E1/E2)/E3)/E4. The semantics of a path expression are thus defined by the semantics of the binary "/" operator, which is defined in §3.3.1.1

I would also suggest adding a Note: Although the semantics describe the evaluation of a path with more than two steps as proceeding from left to right, the "/" operator is in most cases associative, so evaluation from right to left usually delivers the same result. The cases where "/" is not associative arise when the functions fn:position() and fn:last() are used: A/B/position() delivers a sequence of integers from 1 to the size of (A/B), whereas A/(B/position()) restarts the counting at each B element.

10. §3.3.2.2 "A name test is true if and only if the kind of the node is the principal node kind for the step axis and the expanded QName of the node is equal (as defined by the eq operator) to the expanded QName specified by the name test." We've just said that a wildcard is a name test, and this doesn't "specify" an expanded QName. I suggest structuring this as:

A node test is either an EQName, a wildcard, or a kind test.

and then split the rules that follow into these three cases.

11. §3.5 last bullet "Unary operators have higher precedence than binary operators" - should qualify this with: (other than "!", "/", and "[]")

12. The Note just before 3.6 "Multiple consecutive unary arithmetic operators are permitted by XPath 3.1 for compatibility with [XML Path Language (XPath) Version 1.0]." seems unnecessarily apologetic. It's a perfectly natural thing to allow, not some strange XPath 1.0 weirdness that we perpetuate only because we have to.

to be continued

13. §3.11.1.1 Map Constructors. First note is broken: "In some circumstances, it is necessary to include whitespace before or after the colon of a MapConstructorEntry to ensure that this grammar is correctly parsed it is parsed as intended. MapKeyExpr ends with a name and the MapValueExpr starts with a name.".

14. §3.11.1.1. This Note should be deleted as it is no longer true: "In some edge cases involving numerics, the same key value relationship is not transitive."

15. §3.11.3.2. Note, "the focus for evaluating S is the same ..." Sentence should start with capital letter.

16. §3.11.3.2. I think it's worth a mention (e.g. by way of an example) that $A?2 fails FOAY0001 if ANY array in $A has no member at position 2. (Generally, I think the section on arrays could do more to point out that referencing a non-existent position is a dynamic error).

17. §3.14 "sequence types are used in instance of, cast, castable, and treat expressions." Find some way to start with a capital letter, e.g. "The instance of, cast, castable, and treat expressions are used to test whether a value conforms to a given type or to convert it to an instance of a given type." (No need to mention sequenceType syntax here, it's not used in all these expressions anyway.)

18. §3.14.2 The simplified treatment of cast expressions is good but I would add back: The result of a cast expression is one of the following: (a) a value of the target type (or, in the case of list types, a sequence of values that are instances of the item type of the list type), (b) a type error, if casting from the source type to the target type is not supported (for example attempting to convert an integer to a date), or (c) a dynamic error, if the particular input value cannot be converted to the target type (for example, attempting to convert the string "three" to an integer).

19. §3.14.3 castable. We say correctly that this gives an error if evaluating E fails, and returns false if the resulting value cannot be cast to the target type. We've had debates about whether a failure to atomize the result of E throws an error or returns false. I'm surprised that the spec doesn't give the answer to this question. I think the agreed answer is that a failure to evaluate E *or to atomize its value* is reported as an error.

20. §3.15 simple map operator. Let's try to introduce this with something less vacuous than "The simple map operator "!" is used for simple mappings". Replace the first para by "A mapping expression S!E evaluates the expression E once for every item in the sequence obtained by evaluating S. The simple mapping operator "!" can be applied to any sequence, regardless of the types of its items, and it can deliver a mixed sequence of nodes, atomic values, and functions. Unlike the similar "/" operator, it does not sort nodes into document order or eliminate duplicates."

21. §3.15 The second para ends with "otherwise the order of the returned sequence is implementation-dependent." There is no "if" to go with this "otherwise". I suspect it is XQuery text that's conditional on ordering mode.

22. §3.15 We provide some rather complex examples where "!" is combined with "/", but we don't provide any simple examples where it is used on its own. Suggestions:

fn:string-join((1 to $n)!"*") - returns a string containing $n asterisks

$values!(.*.) => fn:sum() - returns the sum of the squares of a sequence of numbers (useful in statistical calculations)

string-join(ancestor::*!name(), '/') - returns a path containing the names of the ancestors of an element, separated by '/' characters

23 §3.16 arrow expression. We say "applies a function to the value of a primary expression", but in the syntax it's a unary expression, which doesn't have to be a primary. For example it can be /*/empl/remun/@salary => avg(), where the LHS is quite complex.

24. §3.16 arrow expression. I suggest avoiding the term "unreadable", which is a matter of opinion, by replacing the para under the definition with

This syntax is particularly helpful when applying multiple functions to a value in turn. For example, the following expression invites syntax errors due to misplaced parentheses:

and then replace the unsubstantiated claim "Many people consider the following expression easier to read, and it is much easier to see that the parentheses are balanced:" by "In the following reformulation, it is easier to see that the parentheses are balanced". I would also put whitespace around the arrows to improve readability.

For 13, the quoted text doesn't match what I see in the document.  

https://www.w3.org/XML/Group/qtspecs/specifications/xquery-31/html/xpath-31.html

"In some circumstances, it is necessary to include whitespace before or after the colon of a MapConstructorEntry to ensure that it is parsed as intended."

Committed fixes for all except for 1 and 10.  Leaving bug open and will come back to them later.

Created attachment 1661 [details]
Screen capture to show the problem for point 13

TIFF screen capture

Attached screen capture of DIFF version of document for point 13.

Somehow the issue only appeared in the DIFF version.  Fixed now.

All should be fixed now.  For 10 I addressed the issue wrt wildcards but I opted not to reorganize the section at this point.