[doc/ref] Clarify the difference between search() and leftMatch()

- with respect to %start aka ^
- link to the YSH Regex API doc

BUT I think there is a bug relative to Python -- see survey-str-api.sh.
I think we should change the REG_NOTBOL logic.

Unrelated: document build/doc.sh

Author: Andy C

build/doc.sh

@@ -1,17 +1,29 @@
 #!/usr/bin/env bash
 #
+# Build docs
+#
 # Usage:
 #   build/doc.sh <function name>
+#
+# Examples:
+#
+#   make HTML:
+#     $0 split-and-render doc/json.md
+#     $0 split-and-render doc/ref/chap-type-method.md '' ../../web  # need relative URL
+#
+#   check code in a doc:
+#     $0 run-code-in-doc ysh-io 
+#     $0 run-code-in-doc ref/chap-type-method
+#
+#     $0 run-code-all  # check all code
+#
+#   build docs:
+#     $0 all-ref
+#     $0 all-markdown
 
-set -o nounset
-set -o pipefail
-set -o errexit
-
-# https://oilshell.org/release/$VERSION/
-#  doc/
-#    index.html
-#    INSTALL.html
-#    INSTALL-old.html
+: ${LIB_OSH=stdlib/osh}
+source $LIB_OSH/bash-strict.sh
+source $LIB_OSH/task-five.sh
 
 readonly OILS_VERSION=$(head -n 1 oils-version.txt)
 export OILS_VERSION  # for quick_ref.py
@@ -999,5 +1011,5 @@ compare-golden() {
   diff -r -u _release/VERSION_gold _release/VERSION/ 
 }
 
-"$@"
+task-five "$@"
 

demo/survey-str-api.sh

@@ -185,4 +185,41 @@ pp test_ (''.split(/ dot /))
 EOF
 }
 
+regex-match-vs-search() {
+  echo 'REGEX PYTHON'
+  echo
+
+  # This is a float
+  python3 -c '
+import re
+
+vowels = re.compile("[aeiou]")
+print(vowels.match("hi"))
+print(vowels.search("hi"))
+
+vowelsLeft = re.compile("^[aeiou]")
+
+print(vowelsLeft.match("hi", pos=1))
+print(vowelsLeft.search("hi", pos=1))
+'
+
+  echo
+  echo 'REGEX YSH'
+  echo
+
+  bin/ysh -c '
+var vowels = / [a e i o u] /
+echo $vowels
+
+= "hi".leftMatch(vowels)
+= "hi".search(vowels)
+
+var vowelsLeft = / %start [a e i o u] /
+= "hi".leftMatch(vowelsLeft, pos=1)
+= "hi".search(vowelsLeft, pos=1)
+'
+
+  # does JS have match vs. search?  I think it might use  ^
+}
+
 "$@"

doc/ref/chap-type-method.md

@@ -311,38 +311,49 @@ Respects unicode.
 
 ### search()
 
-Search for the first occurrence of a regex in the string.
+Search for the first occurrence of a regex in the string.  Returns a
+[Match](#Match) value if it matches, or `null`.
 
     var m = 'hi world'.search(/[a e i o u]/)  # search for vowels
-    # matches at position 1 for 'i'
+    = m.start(0)  # => index 1, matching 'i'
 
-Returns a `value.Match()` if it matches, otherwise `null`.
+    var m = 'hi world'.search(/[z]/)
+    = m  # => null
 
-You can start searching in the middle of the string:
+---
+
+The `pos` parameter lets you start searching in the middle of the string:
 
-    var m = 'hi world'.search(/dot 'orld'/, pos=3)
-    # also matches at position 4 for 'o'
+    var m = 'hi world'.search(/[a e i o u]/, pos=3)
+    = m.start(0)  # => index 4, matching 'o'
 
-The `%start` or `^` metacharacter will only match when `pos` is zero.
+Note: the `%start` aka `^` metacharacter will only match when `pos === 0`.
 
 (Similar to Python's `re.search()`.)
 
 ### leftMatch()
 
-`leftMatch()` is like `search()`, but the pattern must match at the beginning of
-the string.  (This is not necessarily the same as including `%start` in the pattern.)
+`leftMatch()` is like `search()`, but the pattern must match at the beginning
+of the string.
+
+    var m = 'hi world'.leftMatch(/[a e i o u]/)
+    = m           # => Null because 'h' is not a vowel
 
-    # match if the first char is a vowel
-    var m = 'hi world'.leftMatch(/[a e i o u]/)  # => Null, 'h' is not a vowel
+    var m = 'ale'.leftMatch(/[a e i o u]/)
+    = m.start(0)  # => index 0 for a
 
-    var m = 'aye'.leftMatch(/[a e i o u]/)
-    # matches 'a'
+(Unlike `search()`, the `%start` aka `^` metcharacter may match when `pos !==
+0`.)
+
+---
 
 `leftMatch()` Can be used to implement lexers that consume every byte of input.
 
     var lexer = / <capture digit+> | <capture space+> /
 
-(Similar to Python's `re.match()`.)
+See [YSH Regex API](../ysh-regex-api.html).
+
+(`leftMatch()` is similar to Python's `re.match()`.)
 
 ### split()