Fix typo in pcre2grep documentation.

git-svn-id: svn://vcs.exim.org/pcre2/code/trunk@521 6239d852-aaf2-0410-a92c-79f79f948069

1 files changed, 66 insertions, 15 deletions

diff --git a/doc/pcre2grep.txt b/doc/pcre2grep.txt
index 29cd75c..9ee7165 100644
--- a/doc/pcre2grep.txt
+++ b/doc/pcre2grep.txt
@@ -725,35 +725,86 @@ OPTIONS WITH DATA
        equals character. Otherwise pcre2grep will assume that it has no data.
 
 
+CALLING EXTERNAL SCRIPTS
+
+       On non-Windows systems, pcre2grep has, by default, support for  calling
+       external  programs  or scripts during matching by making use of PCRE2's
+       callout facility. However, this support can be disabled when  pcre2grep
+       is  built.   You can find out whether your binary has support for call-
+       outs by running it with the  --help  option.  If  the  support  is  not
+       enabled, all callouts in patterns are ignored by pcre2grep.
+
+       A  callout  in a PCRE2 pattern is of the form (?C<arg>) where the argu-
+       ment is either a number or a quoted string (see the pcre2callout  docu-
+       mentation  for  details).  Numbered  callouts are ignored by pcre2grep.
+       String arguments are parsed as a list of substrings separated  by  pipe
+       (vertical  bar)  characters.  The first substring must be an executable
+       name, with the following substrings specifying arguments:
+
+         executable_name|arg1|arg2|...
+
+       Any substring  (including  the  executable  name)  may  contain  escape
+       sequences  started  by  a dollar character: $<digits> or ${<digits>} is
+       replaced by the captured substring of the given decimal  number,  which
+       must  be greater than zero. If the number is greater than the number of
+       capturing substrings, or if the capture is unset,  the  replacement  is
+       empty.
+
+       Any  other  character  is  substituted  by itself. In particular, $$ is
+       replaced by a single dollar and $| is replaced  by  a  pipe  character.
+       Here is an example:
+
+         echo -e "abcde\n12345" | pcre2grep \
+           '(?x)(.)(..(.))
+           (?C"/bin/echo|Arg1: [$1] [$2] [$3]|Arg2: $|${1}$| ($4)")()' -
+
+         Output:
+
+           Arg1: [a] [bcd] [d] Arg2: |a| ()
+           abcde
+           Arg1: [1] [234] [4] Arg2: |1| ()
+           12345
+
+       The parameters for the execv() system call that is used to run the pro-
+       gram or script are zero-terminated strings. This means that binary zero
+       characters  in the callout argument will cause premature termination of
+       their substrings, and therefore  should  not  be  present.  Any  syntax
+       errors  in  the  string  (for example, a dollar not followed by another
+       character) cause the callout to be  ignored.  If  running  the  program
+       fails for any reason (including the non-existence of the executable), a
+       local matching failure occurs and the matcher backtracks in the  normal
+       way.
+
+
 MATCHING ERRORS
 
-       It is possible to supply a regular expression that takes  a  very  long
-       time  to  fail  to  match certain lines. Such patterns normally involve
-       nested indefinite repeats, for example: (a+)*\d when matched against  a
-       line  of  a's  with  no  final digit. The PCRE2 matching function has a
-       resource limit that causes it to abort in these circumstances. If  this
-       happens,  pcre2grep  outputs  an error message and the line that caused
-       the problem to the standard error stream. If there  are  more  than  20
+       It  is  possible  to supply a regular expression that takes a very long
+       time to fail to match certain lines.  Such  patterns  normally  involve
+       nested  indefinite repeats, for example: (a+)*\d when matched against a
+       line of a's with no final digit. The  PCRE2  matching  function  has  a
+       resource  limit that causes it to abort in these circumstances. If this
+       happens, pcre2grep outputs an error message and the  line  that  caused
+       the  problem  to  the  standard error stream. If there are more than 20
        such errors, pcre2grep gives up.
 
-       The  --match-limit  option  of pcre2grep can be used to set the overall
-       resource limit; there is a second option called --recursion-limit  that
-       sets  a limit on the amount of memory (usually stack) that is used (see
+       The --match-limit option of pcre2grep can be used to  set  the  overall
+       resource  limit; there is a second option called --recursion-limit that
+       sets a limit on the amount of memory (usually stack) that is used  (see
        the discussion of these options above).
 
 
 DIAGNOSTICS
 
        Exit status is 0 if any matches were found, 1 if no matches were found,
-       and  2  for syntax errors, overlong lines, non-existent or inaccessible
-       files (even if matches were found in other files) or too many  matching
+       and 2 for syntax errors, overlong lines, non-existent  or  inaccessible
+       files  (even if matches were found in other files) or too many matching
        errors. Using the -s option to suppress error messages about inaccessi-
        ble files does not affect the return code.
 
 
 SEE ALSO
 
-       pcre2pattern(3), pcre2syntax(3).
+       pcre2pattern(3), pcre2syntax(3), pcre2callout(3).
 
 
 AUTHOR
@@ -765,5 +816,5 @@ AUTHOR
 
 REVISION
 
-       Last updated: 03 January 2015
-       Copyright (c) 1997-2015 University of Cambridge.
+       Last updated: 06 April 2016
+       Copyright (c) 1997-2016 University of Cambridge.