From caeca0bf6b4dd26026df884e32ca3915f0e1b780 Mon Sep 17 00:00:00 2001
From: Nuri Jung <jnooree@gmail.com>
Date: Tue, 22 Feb 2022 10:32:37 +0000
Subject: [PATCH] docs: regexp: Document the platform dependency

Patch by Nuri Jung; extension to cover PCRE by me.  See #747.

Fixes #747.
---
 docs/highlighters/regexp.md | 41 ++++++++++++++++++++++++++++++++++---
 1 file changed, 38 insertions(+), 3 deletions(-)

diff --git a/docs/highlighters/regexp.md b/docs/highlighters/regexp.md
index 5c8a89e..8f96826 100644
--- a/docs/highlighters/regexp.md
+++ b/docs/highlighters/regexp.md
@@ -12,11 +12,44 @@ To use this highlighter, associate regular expressions with styles in the
 
 ```zsh
 typeset -A ZSH_HIGHLIGHT_REGEXP
-ZSH_HIGHLIGHT_REGEXP+=('\bsudo\b' fg=123,bold)
+ZSH_HIGHLIGHT_REGEXP+=('^rm .*' fg=red,bold)
 ```
 
-This will highlight "sudo" only as a complete word, i.e., "sudo cmd", but not
-"sudoedit"
+This will highlight lines that start with a call to the `rm` command.
+
+The regular expressions flavour used is [PCRE][pcresyntax] when the
+`RE_MATCH_PCRE` option is set and POSIX Extended Regular Expressions (ERE),
+as implemented by the platform's C library, otherwise.  For details on the
+latter, see [the `zsh/regex` module's documentation][MAN_ZSH_REGEX] and the
+`regcomp(3)` and `re_format(7)` manual pages on your system.
+
+For instance, to highlight `sudo` only as a complete word, i.e., `sudo cmd`,
+but not `sudoedit`, one might use:
+
+* When the `RE_MATCH_PCRE` is set:
+
+    ```zsh
+    typeset -A ZSH_HIGHLIGHT_REGEXP
+    ZSH_HIGHLIGHT_REGEXP+=('\bsudo\b' fg=123,bold)
+    ```
+
+* When the `RE_MATCH_PCRE` is unset, on platforms with GNU `libc` (e.g., many GNU/Linux distributions):
+
+    ```zsh
+    typeset -A ZSH_HIGHLIGHT_REGEXP
+    ZSH_HIGHLIGHT_REGEXP+=('\<sudo\>' fg=123,bold)
+    ```
+
+* When the `RE_MATCH_PCRE` is unset, on BSD-based platforms (e.g., macOS):
+
+    ```zsh
+    typeset -A ZSH_HIGHLIGHT_REGEXP
+    ZSH_HIGHLIGHT_REGEXP+=('[[:<:]]sudo[[:>:]]' fg=123,bold)
+    ```
+
+Note, however, that PCRE and POSIX ERE have a large common subset:
+for instance, the regular expressions `[abc]`, `a*`, and `(a|b)` have the same
+meaning in both flavours.
 
 The syntax for values is the same as the syntax of "types of highlighting" of
 the zsh builtin `$zle_highlight` array, which is documented in [the `zshzle(1)`
@@ -28,3 +61,5 @@ in [the `zshmisc(1)` manual page][zshmisc-Conditional-Expressions]
 [zshzle-Character-Highlighting]: http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#Character-Highlighting
 [perlretut]: http://perldoc.perl.org/perlretut.html
 [zshmisc-Conditional-Expressions]: http://zsh.sourceforge.net/Doc/Release/Conditional-Expressions.html#Conditional-Expressions
+[MAN_ZSH_REGEX]: https://zsh.sourceforge.io/Doc/Release/Zsh-Modules.html#The-zsh_002fregex-Module
+[pcresyntax]: https://www.pcre.org/original/doc/html/pcresyntax.html