Fix SYNTAX documentation for escaped metacharacters.

diff --git a/doc/SYNTAX.md b/doc/SYNTAX.md
index 18ca16405175175775c7b6176145c4a9133d4e06..2820598cffa98c35ff13f83c95c522f715466c61 100644 (file)
--- a/doc/SYNTAX.md
+++ b/doc/SYNTAX.md
@@ -91,12 +91,14 @@ You usually want this flag set unless you have turned on `ONIG_SYN_OP_VARIABLE_M
 so that you can use a metacharacter other than `*` instead.\r
 \r
 \r
-### 3. ONIG_SYN_OP_ESC_ASTERISK_ZERO_INF (disable `\*`)\r
+### 3. ONIG_SYN_OP_ESC_ASTERISK_ZERO_INF (enable `r\*`)\r
 \r
 _Set in: none_\r
 \r
-This flag _disables_ the ability of the escape metacharacter (usually `\`) to escape\r
-the `*` metacharacter.  You usually want to leave this flag unset.\r
+Enables support for an escaped `r\*` metacharacter, meaning "zero or more r's."  This is\r
+useful if you have disabled support for the normal `r*` metacharacter because you want `*`\r
+to simply match a literal `*` character, but you still want some way of activating "zero or more"\r
+behavior.\r
 \r
 \r
 ### 4. ONIG_SYN_OP_PLUS_ONE_INF (enable `r+`)\r
@@ -108,12 +110,14 @@ You usually want this flag set unless you have turned on `ONIG_SYN_OP_VARIABLE_M
 so that you can use a metacharacter other than `+` instead.\r
 \r
 \r
-### 5. ONIG_SYN_OP_ESC_PLUS_ONE_INF (disable `\+`)\r
+### 5. ONIG_SYN_OP_ESC_PLUS_ONE_INF (enable `r\+`)\r
 \r
 _Set in: Grep_\r
 \r
-This flag _disables_ the ability of the escape metacharacter (usually `\`) to escape\r
-the `+` metacharacter.  You usually want to leave this flag unset.\r
+Enables support for an escaped `r\+` metacharacter, meaning "one or more r's."  This is\r
+useful if you have disabled support for the normal `r+` metacharacter because you want `+`\r
+to simply match a literal `+` character, but you still want some way of activating "one or more"\r
+behavior.\r
 \r
 \r
 ### 6. ONIG_SYN_OP_QMARK_ZERO_ONE (enable `r?`)\r
@@ -125,12 +129,14 @@ You usually want this flag set unless you have turned on `ONIG_SYN_OP_VARIABLE_M
 so that you can use a metacharacter other than `?` instead.\r
 \r
 \r
-### 7. ONIG_SYN_OP_ESC_QMARK_ZERO_ONE (disable `\?`)\r
+### 7. ONIG_SYN_OP_ESC_QMARK_ZERO_ONE (enable `r\?`)\r
 \r
 _Set in: Grep_\r
 \r
-This flag _disables_ the ability of the escape metacharacter (usually `\`) to escape\r
-the `?` metacharacter.  You usually want to leave this flag unset.\r
+Enables support for an escaped `r\?` metacharacter, meaning "zero or one r" or "an optional\r
+r."  This is useful if you have disabled support for the normal `r?` metacharacter because\r
+you want `?` to simply match a literal `?` character, but you still want some way of activating\r
+"optional" behavior.\r
 \r
 \r
 ### 8. ONIG_SYN_OP_BRACE_INTERVAL (enable `r{l,u}`)\r
@@ -150,15 +156,14 @@ this form also allows `r{,upper}` to be equivalent to `r{0,upper}`; otherwise,
 `r{,upper}` will be treated as an error.\r
 \r
 \r
-### 9. ONIG_SYN_OP_ESC_BRACE_INTERVAL (disable `\{` and `\}`)\r
+### 9. ONIG_SYN_OP_ESC_BRACE_INTERVAL (enable `\{` and `\}`)\r
 \r
 _Set in: PosixBasic, Emacs, Grep_\r
 \r
-This flag _disables_ the ability of the escape metacharacter (usually `\`) to escape\r
-the `{` and `}` metacharacters.  With this flag clear, `\{` and `\}` can be used to\r
-escape curly braces, if curly braces are special; but with this flag set, `\` will\r
-have no special meaning before a curly brace and will simply be treated as a literal\r
-backslash (or as whatever metacharacter escaping has been assigned to).\r
+Enables support for an escaped `r\{lower,upper\}` range form.  This is useful if you\r
+have disabled support for the normal `r{...}` range form and want curly braces to simply\r
+match literal curly brace characters, but you still want some way of activating\r
+"range" behavior.\r
 \r
 \r
 ### 10. ONIG_SYN_OP_VBAR_ALT (enable `r|s`)\r
@@ -169,15 +174,13 @@ Enables support for the common `r|s` alternation operator.  You usually want thi
 flag set.\r
 \r
 \r
-### 11. ONIG_SYN_OP_VBAR_ALT (disable `\|`)\r
+### 11. ONIG_SYN_OP_VBAR_ALT (enable `\|`)\r
 \r
 _Set in: Emacs, Grep_\r
 \r
-This flag _disables_ the ability of the escape metacharacter (usually `\`) to escape\r
-the `|` metacharacter.  With this flag clear, `\|` can be used to escape vertical bars,\r
-if vertical bars are special; but with this flag set, `\` will have no special meaning\r
-before a vertical bar and will simply be treated as a literal backslash (or as whatever\r
-metacharacter escaping has been assigned to).\r
+Enables support for an escaped `r\|s` alternation form.  This is useful if you\r
+have disabled support for the normal `r|s` alternation form and want `|` to simply\r
+match a literal `|` character, but you still want some way of activating "alternate" behavior.\r
 \r
 \r
 ### 12. ONIG_SYN_OP_LPAREN_SUBEXP (enable `(r)`)\r
@@ -192,11 +195,10 @@ want this flag set.
 \r
 _Set in: PosixBasic, Emacs, Grep_\r
 \r
-This flag _disables_ the ability of the escape metacharacter (usually `\`) to escape\r
-the `(` and `)` grouping metacharacters.  With this flag clear, `\(` and `\)` can be\r
-used to escape parentheses, if parentheses are special; but with this flag set, `\`\r
-will have no special meaning before a parenthesis and will simply be treated as a\r
-literal backslash (or as whatever metacharacter escaping has been assigned to).\r
+Enables support for escaped `\(...\)` grouping-and-capturing operators.  This is useful if you\r
+have disabled support for the normal `(...)` grouping-and-capturing operators and want\r
+parentheses to simply match literal parenthesis characters, but you still want some way of\r
+activating "grouping" or "capturing" behavior.\r
 \r
 \r
 ### 14. ONIG_SYN_OP_ESC_AZ_BUF_ANCHOR (enable `\A` and `\Z` and `\z`)\r