update documentation of graph references in Cypher 25

Author: nadja-muller

modules/ROOT/pages/values-and-types/graph-references.adoc

@@ -26,13 +26,17 @@ These include:
 [[rules]]
 == Rules
 
-The following rules apply for graph references when using identifiers (static graph references, administration commands) or the `graph.byName` functions:
-
-* Unquoted dots are separators between a composite database and its constituent. 
-For example, `composite.db1` represents the constituent `composite.db1` in the composite database `composite`.
-To refer to a database with a dot (`.`) in its name, quote the graph reference instead: `++`composite.db1`++`.
-* When resolving a graph reference within a graph function, the string argument is parsed like a static graph reference.
-Thus, `USE graph.byName(<graph-reference>)` is typically equivalent to `USE <graph-reference>`.
-However, escaping rules for xref::syntax/naming.adoc#symbolic-names-escaping-rules[symbolic names] are applied to the argument.
-For `STRING` literals, both the xref:values-and-types/boolean-numeric-string.adoc#string-literal-escape-sequences[escaping rules] (during query parsing) and xref::syntax/naming.adoc#symbolic-names-escaping-rules[symbolic names] (during graph reference evaluation) are applied.
-For example, the graph reference in `USE graph.byName('+composite.1\\u0041+')` resolves to the constituent `composite.1a` of the composite database `composite`.
+The following rules apply for graph references when using identifiers (static graph references, administration commands) or the `graph.byName` functions.
+
+`USE graph.byName(<graph-reference>)` is typically equivalent to `USE <graph-reference>`. There may be differences if the name contains special characters:
+
+* Graph references passed as identifiers such as `USE <graph-reference>` apply the escaping rules of xref::syntax/naming.adoc#symbolic-names-escaping-rules[symbolic names]. Graph names can either be unquoted or need to be quoted in its entirety, e.g. `USE neo4j` or `USE `db-with-dash``.
+
+* Graph references passed as graph functions such as `USE graph.byName(<graph-reference>)` apply the escaping rules of xref:values-and-types/boolean-numeric-string.adoc#string-literal-escape-sequences[string literals]. Note that quotes are considered as part of the name, e.g. `USE graph.byName('`db-with-dash`') would try to resolve the graph reference ``db-with-dash``.
+
+
+For example, the graph reference `db-with-dash` can be passed as:
+
+* `USE `db-with-dash``
+* `USE graph.byName('db-with-dash')`
+* `USE graph.byName($param)` with parameter `db-with-dash`