From c98632431adc7284f70f9b4b3b56d7d198d278f4 Mon Sep 17 00:00:00 2001
From: Nuri Jung <jnooree@gmail.com>
Date: Thu, 2 Jul 2020 00:49:57 +0900
Subject: [PATCH] Change document structure

This changes document structure and adds comments for the platform-dependency
of regular expressions.

Fixes #746.
---
 docs/highlighters/regexp.md | 44 ++++++++++++++++++-------------------
 1 file changed, 21 insertions(+), 23 deletions(-)

diff --git a/docs/highlighters/regexp.md b/docs/highlighters/regexp.md
index 2c98995..62f1879 100644
--- a/docs/highlighters/regexp.md
+++ b/docs/highlighters/regexp.md
@@ -10,37 +10,35 @@ patterns.
 To use this highlighter, associate regular expressions with styles in the
 `ZSH_HIGHLIGHT_REGEXP` associative array, for example in `~/.zshrc`:
 
-```zsh
-typeset -A ZSH_HIGHLIGHT_REGEXP
-ZSH_HIGHLIGHT_REGEXP+=('\bsudo\b' fg=123,bold)
-```
+* GNU-Linux
 
-This will highlight "sudo" only as a complete word, i.e., "sudo cmd", but not
-"sudoedit"
+  ```zsh
+  typeset -A ZSH_HIGHLIGHT_REGEXP
+  ZSH_HIGHLIGHT_REGEXP+=('\<sudo\>' fg=123,bold)
+  ```
+
+* BSD-based platforms
+
+  ```zsh
+  typeset -A ZSH_HIGHLIGHT_REGEXP
+  ZSH_HIGHLIGHT_REGEXP+=('[[:<:]]sudo[[:>:]]' fg=123,bold)
+  ```
+
+This will highlight "sudo" only as a complete word, i.e., "sudo cmd", but not "sudoedit".
+
+As in the example, some regex patterns are platform-dependent. Refer to the 
+manual page of `re_format` before applying regular expressions to avoid confusing 
+results. If portability matters, using only [POSIX ERE (extended regular 
+expressions)][POSIX_ERE] could be an option.
 
 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)`
 manual page][zshzle-Character-Highlighting].
 
 See also: [regular expressions tutorial][perlretut], zsh regexp operator `=~`
-in [the `zshmisc(1)` manual page][zshmisc-Conditional-Expressions]
+in [the `zshmisc(1)` manual page][zshmisc-Conditional-Expressions], GNU
 
+[POSIX_ERE]: https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_04
 [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
-
-### Cautions to BSD-based platform users
-
-In BSD-based platform such as macOS, the regex metacharacters with leading backslash (`\`)
-such as `\b`, `\w`, etc. are [not supported](https://stackoverflow.com/a/12696899).
-
-So if you want something like the above example, you should use `[[:<:]]`(matches the beginning of a word)
-with `[[:>:]]`(matches the end of a word). The complete example would be like:
-
-```zsh
-typeset -A ZSH_HIGHLIGHT_REGEXP
-ZSH_HIGHLIGHT_REGEXP+=('[[:<:]]sudo[[:>:]]' fg=123,bold)
-```
-
-For other metacharacters, consider using
-[POSIX ERE](https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_04) instead.