PATCH: Add some more details on pcre callouts

---

I guess most notably, ${.pcre.pos} was not documented at all before, and
it seems fairly important for this feature to be useful. Also, both of
these sections were outside the pcre_match item(), so put them back
inside, and move the -d option description before this long section about
callouts.

 Doc/Zsh/mod_pcre.yo | 16 ++++++++++++----
 1 file changed, 12 insertions(+), 4 deletions(-)

diff --git a/Doc/Zsh/mod_pcre.yo b/Doc/Zsh/mod_pcre.yo
index 41fab44752..364aaee4c5 100644
--- a/Doc/Zsh/mod_pcre.yo
+++ b/Doc/Zsh/mod_pcre.yo
@@ -69,10 +69,18 @@ print -l $accum)
 )
 enditem()
 
-If the regular expression contains callouts, these are executed as shell code.
-During the execution of the callout, the string the regular expression is
-matching against is available in the parameter tt(.pcre.subject). If there is a
-non-zero return status from the shell code, the callout does not match.
+If the regular expression contains string callouts, these are executed as
+shell code, while numerical callouts are ignored. During the execution of the
+callout, the string the regular expression is matching against is available
+in the parameter tt(.pcre.subject). The parameter tt(.pcre.pos) contains the
+position in that string that is currently being matched against. If there is
+a non-zero return status from the shell code, the callout does not match. Note
+that callouts are not available in the below -pcre-match test condition. It is
+also likely not a good idea to call any pcre related builtins from a callout. As
+an example, the following will print out `tt(bar)':
+
+example(pcre_compile 'foo(?C"echo ${.pcre.subject[${.pcre.pos},-1]}")'
+pcre_match foobar)
 
 The option tt(-d) uses the alternative breadth-first DFA search algorithm of
 pcre. This sets tt(match), or the array given with tt(-a), to all the matches
-- 
2.38.1