Derived documentation update.

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

6 files changed, 97 insertions, 60 deletions

diff --git a/doc/html/pcre2_get_mark.html b/doc/html/pcre2_get_mark.html
index f8e50e3..2b77e42 100644
--- a/doc/html/pcre2_get_mark.html
+++ b/doc/html/pcre2_get_mark.html
@@ -26,11 +26,15 @@ DESCRIPTION
 </b><br>
 <P>
 After a call of <b>pcre2_match()</b> that was passed the match block that is
-this function's argument, this function returns a pointer to the last (*MARK)
-name that was encountered. The name is zero-terminated, and is within the
-compiled pattern. If no (*MARK) name is available, NULL is returned. A (*MARK)
-name may be available after a failed match or a partial match, as well as after
-a successful one.
+this function's argument, this function returns a pointer to the last (*MARK),
+(*PRUNE), or (*THEN) name that was encountered during the matching process. The
+name is zero-terminated, and is within the compiled pattern. The length of the
+name is in the preceding code unit. If no name is available, NULL is returned.
+</P>
+<P>
+After a successful match, the name that is returned is the last one on the 
+matching path. After a failed match or a partial match, the last encountered 
+name is returned.
 </P>
 <P>
 There is a complete description of the PCRE2 native API in the
diff --git a/doc/html/pcre2api.html b/doc/html/pcre2api.html
index 5d3ff6a..4e98cd6 100644
--- a/doc/html/pcre2api.html
+++ b/doc/html/pcre2api.html
@@ -2719,25 +2719,28 @@ undefined.
 </P>
 <P>
 After a successful match, a partial match (PCRE2_ERROR_PARTIAL), or a failure
-to match (PCRE2_ERROR_NOMATCH), a (*MARK) name may be available, and
-<b>pcre2_get_mark()</b> can be called. It returns a pointer to the
-zero-terminated name, which is within the compiled pattern. Otherwise NULL is
-returned. The length of the (*MARK) name (excluding the terminating zero) is
-stored in the code unit that preceeds the name. You should use this instead of
-relying on the terminating zero if the (*MARK) name might contain a binary
-zero.
-</P>
-<P>
-After a successful match, the (*MARK) name that is returned is the
-last one encountered on the matching path through the pattern. After a "no
-match" or a partial match, the last encountered (*MARK) name is returned. For
-example, consider this pattern:
+to match (PCRE2_ERROR_NOMATCH), a (*MARK), (*PRUNE), or (*THEN) name may be
+available. The function <b>pcre2_get_mark()</b> can be called to access this
+name. The same function applies to all three verbs. It returns a pointer to the
+zero-terminated name, which is within the compiled pattern. If no name is
+available, NULL is returned. The length of the name (excluding the terminating
+zero) is stored in the code unit that precedes the name. You should use this
+length instead of relying on the terminating zero if the name might contain a
+binary zero.
+</P>
+<P>
+After a successful match, the name that is returned is the last (*MARK),
+(*PRUNE), or (*THEN) name encountered on the matching path through the pattern.
+Instances of (*PRUNE) and (*THEN) without names are ignored. Thus, for example,
+if the matching path contains (*MARK:A)(*PRUNE), the name "A" is returned.
+After a "no match" or a partial match, the last encountered name is returned.
+For example, consider this pattern:
 <pre>
   ^(*MARK:A)((*MARK:B)a|b)c
 </pre>
-When it matches "bc", the returned mark is A. The B mark is "seen" in the first
+When it matches "bc", the returned name is A. The B mark is "seen" in the first
 branch of the group, but it is not on the matching path. On the other hand,
-when this pattern fails to match "bx", the returned mark is B.
+when this pattern fails to match "bx", the returned name is B.
 </P>
 <P>
 After a successful match, a partial match, or one of the invalid UTF errors
@@ -3124,12 +3127,12 @@ length is in code units, not bytes.
 In the replacement string, which is interpreted as a UTF string in UTF mode,
 and is checked for UTF validity unless the PCRE2_NO_UTF_CHECK option is set, a
 dollar character is an escape character that can specify the insertion of
-characters from capturing groups or (*MARK) items in the pattern. The following
-forms are always recognized:
+characters from capturing groups or (*MARK), (*PRUNE), or (*THEN) items in the
+pattern. The following forms are always recognized:
 <pre>
   $$                  insert a dollar character
   $&#60;n&#62; or ${&#60;n&#62;}      insert the contents of group &#60;n&#62;
-  $*MARK or ${*MARK}  insert the name of the last (*MARK) encountered
+  $*MARK or ${*MARK}  insert a (*MARK), (*PRUNE), or (*THEN) name
 </pre>
 Either a group number or a group name can be given for &#60;n&#62;. Curly brackets are
 required only if the following character would be interpreted as part of the
@@ -3138,15 +3141,19 @@ For example, if the pattern a(b)c is matched with "=abc=" and the replacement
 string "+$1$0$1+", the result is "=+babcb+=".
 </P>
 <P>
-The facility for inserting a (*MARK) name can be used to perform simple
-simultaneous substitutions, as this <b>pcre2test</b> example shows:
+$*MARK inserts the name from the last encountered (*MARK), (*PRUNE), or (*THEN)
+on the matching path that has a name. (*MARK) must always include a name, but
+(*PRUNE) and (*THEN) need not. For example, in the case of (*MARK:A)(*PRUNE)
+the name inserted is "A", but for (*MARK:A)(*PRUNE:B) the relevant name is "B".
+This facility can be used to perform simple simultaneous substitutions, as this
+<b>pcre2test</b> example shows:
 <pre>
-  /(*:pear)apple|(*:orange)lemon/g,replace=${*MARK}
+  /(*MARK:pear)apple|(*MARK:orange)lemon/g,replace=${*MARK}
       apple lemon
    2: pear orange
 </pre>
 As well as the usual options for <b>pcre2_match()</b>, a number of additional
-options can be set in the <i>options</i> argument.
+options can be set in the <i>options</i> argument of <b>pcre2_substitute()</b>.
 </P>
 <P>
 PCRE2_SUBSTITUTE_GLOBAL causes the function to iterate over the subject string,
@@ -3560,7 +3567,7 @@ Cambridge, England.
 </P>
 <br><a name="SEC42" href="#TOC1">REVISION</a><br>
 <P>
-Last updated: 25 September 2017
+Last updated: 13 October 2017
 <br>
 Copyright &copy; 1997-2017 University of Cambridge.
 <br>
diff --git a/doc/html/pcre2grep.html b/doc/html/pcre2grep.html
index b5565a8..0db66ff 100644
--- a/doc/html/pcre2grep.html
+++ b/doc/html/pcre2grep.html
@@ -922,6 +922,10 @@ matches were found in other files) or too many matching errors. Using the
 <b>-s</b> option to suppress error messages about inaccessible files does not
 affect the return code.
 </P>
+<P>
+When run under VMS, the return code is placed in the symbol PCRE2GREP_RC 
+because VMS does not distinguish between exit(0) and exit(1).
+</P>
 <br><a name="SEC13" href="#TOC1">SEE ALSO</a><br>
 <P>
 <b>pcre2pattern</b>(3), <b>pcre2syntax</b>(3), <b>pcre2callout</b>(3).
@@ -937,7 +941,7 @@ Cambridge, England.
 </P>
 <br><a name="SEC15" href="#TOC1">REVISION</a><br>
 <P>
-Last updated: 17 June 2017
+Last updated: 11 October 2017
 <br>
 Copyright &copy; 1997-2017 University of Cambridge.
 <br>
diff --git a/doc/html/pcre2test.html b/doc/html/pcre2test.html
index 12ff36b..3427787 100644
--- a/doc/html/pcre2test.html
+++ b/doc/html/pcre2test.html
@@ -167,7 +167,8 @@ internal binary form of the pattern is output after compilation.
 <b>-C</b>
 Output the version number of the PCRE2 library, and all available information
 about the optional features that are included, and then exit with zero exit
-code. All other options are ignored.
+code. All other options are ignored. If both -C and -LM are present, whichever
+is first is recognized.
 </P>
 <P>
 <b>-C</b> <i>option</i>
@@ -241,6 +242,12 @@ successful compilation, each pattern is passed to the just-in-time compiler, if
 available, and the use of JIT is verified.
 </P>
 <P>
+<b>-LM</b>
+List modifiers: write a list of available pattern and subject modifiers to the 
+standard output, then exit with zero exit code. All other options are ignored. 
+If both -C and -LM are present, whichever is first is recognized.
+</P>
+<P>
 \fB-pattern\fB <i>modifier-list</i>
 Behave as if each pattern line contains the given modifiers.
 </P>
@@ -1020,13 +1027,14 @@ Setting certain match controls
 The following modifiers are really subject modifiers, and are described under
 "Subject Modifiers" below. However, they may be included in a pattern's
 modifier list, in which case they are applied to every subject line that is
-processed with that pattern. They may not appear in <b>#pattern</b> commands.
-These modifiers do not affect the compilation process.
+processed with that pattern. These modifiers do not affect the compilation
+process.
 <pre>
       aftertext                  show text after match
       allaftertext               show text after captures
       allcaptures                show all captures
       allusedtext                show all consulted text
+      altglobal                  alternative global matching
   /g  global                     global matching
       jitstack=&#60;n&#62;               set size of JIT stack
       mark                       show mark values
@@ -1905,7 +1913,7 @@ Cambridge, England.
 </P>
 <br><a name="SEC21" href="#TOC1">REVISION</a><br>
 <P>
-Last updated: 12 July 2017
+Last updated: 17 October 2017
 <br>
 Copyright &copy; 1997-2017 University of Cambridge.
 <br>
diff --git a/doc/pcre2.txt b/doc/pcre2.txt
index fa8c265..d2b9216 100644
--- a/doc/pcre2.txt
+++ b/doc/pcre2.txt
@@ -2647,25 +2647,29 @@ OTHER INFORMATION ABOUT A MATCH
        times, the result is undefined.
 
        After  a  successful match, a partial match (PCRE2_ERROR_PARTIAL), or a
-       failure to match (PCRE2_ERROR_NOMATCH), a (*MARK) name  may  be  avail-
-       able,  and  pcre2_get_mark() can be called. It returns a pointer to the
-       zero-terminated name, which is within the compiled  pattern.  Otherwise
-       NULL  is returned. The length of the (*MARK) name (excluding the termi-
-       nating zero) is stored in the code unit that  preceeds  the  name.  You
-       should  use  this  instead  of  relying  on the terminating zero if the
-       (*MARK) name might contain a binary zero.
-
-       After a successful match, the (*MARK) name that is returned is the last
-       one  encountered  on the matching path through the pattern. After a "no
-       match" or a  partial  match,  the  last  encountered  (*MARK)  name  is
-       returned. For example, consider this pattern:
+       failure to match (PCRE2_ERROR_NOMATCH), a (*MARK), (*PRUNE), or (*THEN)
+       name  may  be available. The function pcre2_get_mark() can be called to
+       access this name. The same function applies  to  all  three  verbs.  It
+       returns a pointer to the zero-terminated name, which is within the com-
+       piled pattern. If no name is available, NULL is returned. The length of
+       the  name  (excluding  the terminating zero) is stored in the code unit
+       that precedes the name. You should use this length instead  of  relying
+       on the terminating zero if the name might contain a binary zero.
+
+       After  a  successful  match,  the  name  that  is  returned is the last
+       (*MARK), (*PRUNE), or (*THEN) name encountered  on  the  matching  path
+       through  the  pattern.  Instances of (*PRUNE) and (*THEN) without names
+       are  ignored.  Thus,  for  example,  if  the  matching  path   contains
+       (*MARK:A)(*PRUNE),  the  name "A" is returned.  After a "no match" or a
+       partial match, the last encountered name  is  returned.   For  example,
+       consider this pattern:
 
          ^(*MARK:A)((*MARK:B)a|b)c
 
-       When  it  matches "bc", the returned mark is A. The B mark is "seen" in
+       When  it  matches "bc", the returned name is A. The B mark is "seen" in
        the first branch of the group, but it is not on the matching  path.  On
        the  other  hand,  when  this pattern fails to match "bx", the returned
-       mark is B.
+       name is B.
 
        After a successful match, a partial match, or one of  the  invalid  UTF
        errors  (for example, PCRE2_ERROR_UTF8_ERR5), pcre2_get_startchar() can
@@ -3027,29 +3031,35 @@ CREATING A NEW STRING WITH SUBSTITUTIONS
        In  the replacement string, which is interpreted as a UTF string in UTF
        mode, and is checked for UTF  validity  unless  the  PCRE2_NO_UTF_CHECK
        option is set, a dollar character is an escape character that can spec-
-       ify the insertion of characters from capturing groups or (*MARK)  items
-       in the pattern. The following forms are always recognized:
+       ify the insertion of  characters  from  capturing  groups  or  (*MARK),
+       (*PRUNE),  or  (*THEN)  items  in  the pattern. The following forms are
+       always recognized:
 
          $$                  insert a dollar character
          $<n> or ${<n>}      insert the contents of group <n>
-         $*MARK or ${*MARK}  insert the name of the last (*MARK) encountered
+         $*MARK or ${*MARK}  insert a (*MARK), (*PRUNE), or (*THEN) name
 
-       Either  a  group  number  or  a  group name can be given for <n>. Curly
-       brackets are required only if the following character would  be  inter-
+       Either a group number or a group name  can  be  given  for  <n>.  Curly
+       brackets  are  required only if the following character would be inter-
        preted as part of the number or name. The number may be zero to include
-       the entire matched string.   For  example,  if  the  pattern  a(b)c  is
-       matched  with "=abc=" and the replacement string "+$1$0$1+", the result
+       the  entire  matched  string.   For  example,  if  the pattern a(b)c is
+       matched with "=abc=" and the replacement string "+$1$0$1+", the  result
        is "=+babcb+=".
 
-       The facility for inserting a (*MARK) name can be used to perform simple
-       simultaneous substitutions, as this pcre2test example shows:
+       $*MARK inserts the name from the last encountered (*MARK), (*PRUNE), or
+       (*THEN) on the matching path that  has  a  name.  (*MARK)  must  always
+       include  a name, but (*PRUNE) and (*THEN) need not. For example, in the
+       case  of  (*MARK:A)(*PRUNE)  the  name  inserted  is   "A",   but   for
+       (*MARK:A)(*PRUNE:B)  the  relevant  name  is "B".  This facility can be
+       used to perform simple simultaneous substitutions,  as  this  pcre2test
+       example shows:
 
-         /(*:pear)apple|(*:orange)lemon/g,replace=${*MARK}
+         /(*MARK:pear)apple|(*MARK:orange)lemon/g,replace=${*MARK}
              apple lemon
           2: pear orange
 
        As  well as the usual options for pcre2_match(), a number of additional
-       options can be set in the options argument.
+       options can be set in the options argument of pcre2_substitute().
 
        PCRE2_SUBSTITUTE_GLOBAL causes the function to iterate over the subject
        string,  replacing  every  matching substring. If this is not set, only
@@ -3437,7 +3447,7 @@ AUTHOR
 
 REVISION
 
-       Last updated: 25 September 2017
+       Last updated: 13 October 2017
        Copyright (c) 1997-2017 University of Cambridge.
 ------------------------------------------------------------------------------
  
diff --git a/doc/pcre2grep.txt b/doc/pcre2grep.txt
index 7dee204..5067827 100644
--- a/doc/pcre2grep.txt
+++ b/doc/pcre2grep.txt
@@ -903,6 +903,10 @@ DIAGNOSTICS
        errors. Using the -s option to suppress error messages about inaccessi-
        ble files does not affect the return code.
 
+       When  run  under  VMS,  the  return  code  is  placed  in  the   symbol
+       PCRE2GREP_RC  because  VMS  does  not  distinguish  between exit(0) and
+       exit(1).
+
 
 SEE ALSO
 
@@ -918,5 +922,5 @@ AUTHOR
 
 REVISION
 
-       Last updated: 17 June 2017
+       Last updated: 11 October 2017
        Copyright (c) 1997-2017 University of Cambridge.