From 6119920f264cc78d25927db84b5ffca2f1092fa6 Mon Sep 17 00:00:00 2001
From: "Philip.Hazel" <Philip.Hazel@gmail.com>
Date: Thu, 3 Sep 2015 15:53:14 +0000
Subject: [PATCH] Clarify semantics of the POSIX wrapper.

---
 doc/pcre2posix.3 | 26 +++++++++++++++-----------
 doc/pcre2test.1  | 12 ++++++++----
 2 files changed, 23 insertions(+), 15 deletions(-)

diff --git a/doc/pcre2posix.3 b/doc/pcre2posix.3
index b666975..5d5164b 100644
--- a/doc/pcre2posix.3
+++ b/doc/pcre2posix.3
@@ -1,4 +1,4 @@
-.TH PCRE2POSIX 3 "20 October 2014" "PCRE2 10.00"
+.TH PCRE2POSIX 3 "03 September 2015" "PCRE2 10.21"
 .SH NAME
 PCRE2 - Perl-compatible regular expressions (revised API)
 .SH "SYNOPSIS"
@@ -145,7 +145,7 @@ use the contents of the \fIpreg\fP structure. If, for example, you pass it to
 This area is not simple, because POSIX and Perl take different views of things.
 It is not possible to get PCRE2 to obey POSIX semantics, but then PCRE2 was
 never intended to be a POSIX engine. The following table lists the different
-possibilities for matching newline characters in PCRE2:
+possibilities for matching newline characters in Perl and PCRE2:
 .sp
                           Default   Change with
 .sp
@@ -155,7 +155,7 @@ possibilities for matching newline characters in PCRE2:
   $ matches \en in middle     no     PCRE2_MULTILINE
   ^ matches \en in middle     no     PCRE2_MULTILINE
 .sp
-This is the equivalent table for POSIX:
+This is the equivalent table for a POSIX-compatible pattern matcher:
 .sp
                           Default   Change with
 .sp
@@ -165,13 +165,17 @@ This is the equivalent table for POSIX:
   $ matches \en in middle     no     REG_NEWLINE
   ^ matches \en in middle     no     REG_NEWLINE
 .sp
-PCRE2's behaviour is the same as Perl's, except that there is no equivalent for
-PCRE2_DOLLAR_ENDONLY in Perl. In both PCRE2 and Perl, there is no way to stop
-newline from matching [^a].
+This behaviour is not what happens when PCRE2 is called via its POSIX
+API. By default, PCRE2's behaviour is the same as Perl's, except that there is
+no equivalent for PCRE2_DOLLAR_ENDONLY in Perl. In both PCRE2 and Perl, there
+is no way to stop newline from matching [^a].
 .P
-The default POSIX newline handling can be obtained by setting PCRE2_DOTALL and
-PCRE2_DOLLAR_ENDONLY, but there is no way to make PCRE2 behave exactly as for
-the REG_NEWLINE action.
+Default POSIX newline handling can be obtained by setting PCRE2_DOTALL and
+PCRE2_DOLLAR_ENDONLY when calling \fBpcre2_compile()\fP directly, but there is
+no way to make PCRE2 behave exactly as for the REG_NEWLINE action. When using
+the POSIX API, passing REG_NEWLINE to PCRE2's \fBregcomp()\fP function
+causes PCRE2_MULTILINE to be passed to \fBpcre2_compile()\fP, and REG_DOTALL 
+passes PCRE2_DOTALL. There is no way to pass PCRE2_DOLLAR_ENDONLY.
 .
 .
 .SH "MATCHING A PATTERN"
@@ -263,6 +267,6 @@ Cambridge, England.
 .rs
 .sp
 .nf
-Last updated: 20 October 2014
-Copyright (c) 1997-2014 University of Cambridge.
+Last updated: 03 September 2015
+Copyright (c) 1997-2015 University of Cambridge.
 .fi
diff --git a/doc/pcre2test.1 b/doc/pcre2test.1
index 523dfc1..df822ae 100644
--- a/doc/pcre2test.1
+++ b/doc/pcre2test.1
@@ -1,4 +1,4 @@
-.TH PCRE2TEST 1 "30 August 2015" "PCRE 10.21"
+.TH PCRE2TEST 1 "03 September 2015" "PCRE 10.21"
 .SH NAME
 pcre2test - a program for testing Perl-compatible regular expressions.
 .SH SYNOPSIS
@@ -667,8 +667,12 @@ suite.
 .sp
 The \fB/posix\fP modifier causes \fBpcre2test\fP to call PCRE2 via the POSIX
 wrapper API rather than its native API. This supports only the 8-bit library.
-When the POSIX API is being used, the following pattern modifiers set options
-for the \fBregcomp()\fP function:
+Note that it does not imply POSIX matching semantics; for more detail see the
+.\" HREF
+\fBpcre2posix\fP
+.\"
+documentation. When the POSIX API is being used, the following pattern
+modifiers set options for the \fBregcomp()\fP function:
 .sp
   caseless           REG_ICASE
   multiline          REG_NEWLINE
@@ -1453,6 +1457,6 @@ Cambridge, England.
 .rs
 .sp
 .nf
-Last updated: 30 August 2015
+Last updated: 03 September 2015
 Copyright (c) 1997-2015 University of Cambridge.
 .fi