use quote in backticks rather than escape (#1111)

Ops Manual PR: neo4j/docs-operations#1959
neo4j · Nov 14, 2024 · fbbc11d · fbbc11d
1 parent 2d3c71b
commit fbbc11d
Show file tree

Hide file tree

Showing 4 changed files with 21 additions and 21 deletions.
diff --git a/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc b/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc
@@ -49,8 +49,8 @@ MATCH (where {...})
 ----
 MATCH (...)-[where {...}]->()
 ----
-a| The unescaped variable named `where` (or any casing variant, like `WHERE`) used in a node or relationship pattern followed directly by a property key-value expression is deprecated.
-To continue using variables with this name, use backticks to escape the variable name:
+a| The variable named `where` (or any casing variant, like `WHERE`) used in a node or relationship pattern followed directly by a property key-value expression is deprecated.
+To continue using variables with this name, use backticks to quote the variable name:
 
 * Node patterns: `MATCH (++`where`++ { ... })`
 * Relationship patterns: `MATCH (...)-[++`where`++ { ... }]->()`
@@ -78,8 +78,8 @@ label:deprecated[]
 ----
 CASE x ... WHEN is :: STRING THEN ... END
 ----
-a| Using an unescaped variable named `is` (or any casing variant, like `IS`) as a `WHEN` operand in a xref:queries/case.adoc#case-simple[simple `CASE`] expression is deprecated.
-To continue using variables with this name in simple `CASE` expressions, use backticks to escape the variable name: `CASE x ... WHEN ++`is`++ :: STRING THEN ... END`
+a| Using a variable named `is` (or any casing variant, like `IS`) as a `WHEN` operand in a xref:queries/case.adoc#case-simple[simple `CASE`] expression is deprecated.
+To continue using variables with this name in simple `CASE` expressions, use backticks to quote the variable name: `CASE x ... WHEN ++`is`++ :: STRING THEN ... END`
 
 a|
 label:functionality[]
@@ -91,8 +91,8 @@ CASE x ... WHEN contains + 1 THEN ... END
 ----
 CASE x ... WHEN contains - 1 THEN ... END
 ----
-a| Using an unescaped variable named `contains` (or any casing variant, like `CONTAINS`) in addition or subtraction operations within a `WHEN` operand of a xref:queries/case.adoc#case-simple[simple `CASE`] expression is deprecated.
-To continue using variables with this name, use backticks to escape the variable name:
+a| Using a variable named `contains` (or any casing variant, like `CONTAINS`) in addition or subtraction operations within a `WHEN` operand of a xref:queries/case.adoc#case-simple[simple `CASE`] expression is deprecated.
+To continue using variables with this name, use backticks to quote the variable name:
 
 * Additions: `CASE x ... WHEN ++`contains`++ + 1 THEN ... END` 
 * Subtractions: `CASE x ... WHEN ++`contains`++ - 1 THEN ... END`
@@ -107,8 +107,8 @@ CASE x ... WHEN in[1] THEN ... END
 ----
 CASE x ... WHEN in["abc"] THEN ... END
 ----
-a| Using the `[]` operator on an unescaped variable named `in` (or any casing variant, like `IN`) within a `WHEN` operand of a xref:queries/case.adoc#case-simple[simple `CASE`] expression is deprecated.
-To continue using variables with this name, use backticks to escape the variable name:
+a| Using the `[]` operator on a variable named `in` (or any casing variant, like `IN`) within a `WHEN` operand of a xref:queries/case.adoc#case-simple[simple `CASE`] expression is deprecated.
+To continue using variables with this name, use backticks to quote the variable name:
 
 * `CASE x ... WHEN ++`in`++[1] THEN ... END` 
 * `CASE x ... WHEN ++`in`++["abc"] THEN ... END`
@@ -1000,9 +1000,9 @@ label:deprecated[]
 RETURN 1 as my\u0085identifier
 ----
 a|
-The Unicode character \`\u0085` is deprecated for unescaped identifiers and will be considered as a whitespace character in the future.
-To continue using it, escape the identifier by adding backticks around the identifier.
-This applies to all unescaped identifiers in Cypher, such as label expressions, properties, variable names or parameters.
+The Unicode character \`\u0085` is deprecated for identifiers not quoted in backticks and will be considered as a whitespace character in the future.
+To continue using it, quote the identifier with backticks.
+This applies to all identifiers in Cypher, such as label expressions, properties, variable names or parameters.
 In the given example, the quoted identifier would be \`my�identifier`.
 
 a|
@@ -1013,8 +1013,8 @@ label:deprecated[]
 RETURN 1 as my$Identifier
 ----
 a|
-The character with the Unicode representation \`\u0024` is deprecated for unescaped identifiers and will not be supported in the future. To continue using it, escape the identifier by adding backticks around the identifier.
-This applies to all unescaped identifiers in Cypher, such as label expressions, properties, variable names or parameters. In the given example, the quoted identifier would be \`my$identifier`.
+The character with the Unicode representation \`\u0024` is deprecated for identifiers not quoted in backticks and will not be supported in the future. To continue using it, quote the identifier with backticks.
+This applies to all identifiers in Cypher, such as label expressions, properties, variable names or parameters. In the given example, the quoted identifier would be \`my$identifier`.
 
 The following Unicode Characters are deprecated in identifiers:
 '\u0000', '\u0001', '\u0002', '\u0003', '\u0004', '\u0005', '\u0006', '\u0007',
@@ -2682,7 +2682,7 @@ label:deprecated[]
 CREATE DATABASE databaseName.withDot ...
 ----
 a|
-Creating a database with unescaped dots in the name has been deprecated, instead escape the database name:
+Creating a database with dots in the name has been deprecated, instead quote the database name using backticks:
 
 [source, cypher, role="noheader"]
 ----

diff --git a/modules/ROOT/pages/styleguide.adoc b/modules/ROOT/pages/styleguide.adoc
@@ -472,7 +472,7 @@ RETURN 'Cypher\'s a nice language', "Mats' quote: \"statement\""
 RETURN "Cypher's a nice language", 'Mats\' quote: "statement"'
 ----
 
-* Avoid having to use back-ticks to escape characters and keywords.
+* Avoid using characters and keywords that require the input to be quoted with backticks.
 
 .Bad
 [source, cypher]

diff --git a/modules/ROOT/pages/syntax/naming.adoc b/modules/ROOT/pages/syntax/naming.adoc
@@ -25,23 +25,23 @@ For example, `MATCH (  a  ) RETURN a` is equivalent to `MATCH (a) RETURN a`.
 
 [[symbolic-names-escaping-rules]]
 === Using special characters in names
-Non-alphabetic characters, including numbers, symbols and whitespace characters, *can* be used in names, but *must* be escaped using backticks.
+Non-alphabetic characters, including numbers, symbols and whitespace characters, *can* be used in names, but *must* be quoted using backticks.
 For example: `++`^n`++`, `++`1first`++`, `++`$$n`++`, and `++`my variable has spaces`++`.
-Database names are an exception and may include dots without the need for escaping, although this behavior is deprecated as it may introduce ambiguity when addressing composite databases.
+Database names are an exception and may include dots without the need for quoting using backticks, although this behavior is deprecated as it may introduce ambiguity when addressing composite databases.
 For example: naming a database `foo.bar.baz` is valid, but deprecated. `++`foo.bar.baz`++` is valid.
 
-Within an escaped name, the following escaping sequences are allowed:
+Within a name quoted by backticks, the following character representations are allowed:
 
 [options="header", cols=">1,<2"]
 |===
-|Escape sequence|Character
+| Character representation | Description
 |````| Backtick
 |`\uxxxx`| Unicode UTF-16 code point (4 hex digits must follow the `\u`)
 |===
 
 [NOTE]
 ====
-Using escaped names with unsanitized user input makes you vulnerable to Cypher injection.
+Using names quoted in backticks with unsanitized user input makes you vulnerable to Cypher injection.
 Some techniques to mitigate this are:
 
 * sanitizing (and validating) the user input.

diff --git a/modules/ROOT/pages/syntax/reserved.adoc b/modules/ROOT/pages/syntax/reserved.adoc
@@ -16,7 +16,7 @@ The reserved keywords are not permitted to be used as identifiers in the followi
 * Function names
 * Parameters
 
-If any reserved keyword is escaped -- i.e. is encapsulated by backticks ```, such as `++`AND`++` -- it would become a valid identifier in the above contexts.
+If any reserved keyword is quoted in backticks (```), such as `++`AND`++`, it would become a valid identifier in the above contexts; however, this approach is not recommended.
 
 == Clauses