Documentation update

Author: PhilipHazel

doc/pcre2grep.1

@@ -1,4 +1,4 @@
-.TH PCRE2GREP 1 "20 November 2023" "PCRE2 10.43"
+.TH PCRE2GREP 1 "22 December 2023" "PCRE2 10.43"
 .SH NAME
 pcre2grep - a grep with Perl-compatible regular expressions.
 .SH SYNOPSIS
@@ -43,15 +43,16 @@ For example:
 .sp
   pcre2grep some-pattern file1 - file3
 .sp
-By default, input files are searched line by line. Each line that matches a
-pattern is copied to the standard output, and if there is more than one file,
-the file name is output at the start of each line, followed by a colon.
-However, there are options that can change how \fBpcre2grep\fP behaves. For
-example, the \fB-M\fP option makes it possible to search for strings that span
-line boundaries. What defines a line boundary is controlled by the \fB-N\fP
-(\fB--newline\fP) option. The \fB-h\fP and \fB-H\fP options control whether or
-not file names are shown, and the \fB-Z\fP option changes the file name
-terminator to a zero byte.
+By default, input files are searched line by line, so pattern assertions about
+the beginning and end of a subject string (^, $, \eA, \eZ, and \ez) match at
+the beginning and end of each line. When a line matches a pattern, it is copied
+to the standard output, and if there is more than one file, the file name is
+output at the start of each line, followed by a colon. However, there are
+options that can change how \fBpcre2grep\fP behaves. For example, the \fB-M\fP
+option makes it possible to search for strings that span line boundaries. What
+defines a line boundary is controlled by the \fB-N\fP (\fB--newline\fP) option.
+The \fB-h\fP and \fB-H\fP options control whether or not file names are shown,
+and the \fB-Z\fP option changes the file name terminator to a zero byte.
 .P
 The amount of memory used for buffering files that are being scanned is
 controlled by parameters that can be set by the \fB--buffer-size\fP and
@@ -489,16 +490,22 @@ used. There is no short form for this option.
 .TP
 \fB-M\fP, \fB--multiline\fP
 Allow patterns to match more than one line. When this option is set, the PCRE2
-library is called in "multiline" mode. This allows a matched string to extend
-past the end of a line and continue on one or more subsequent lines. Patterns
-used with \fB-M\fP may usefully contain literal newline characters and internal
-occurrences of ^ and $ characters. The output for a successful match may
-consist of more than one line. The first line is the line in which the match
-started, and the last line is the line in which the match ended. If the matched
-string ends with a newline sequence, the output ends at the end of that line.
-If \fB-v\fP is set, none of the lines in a multi-line match are output. Once a
-match has been handled, scanning restarts at the beginning of the line after
-the one in which the match ended.
+library is called in "multiline" mode, and a match is allowed to continue past
+the end of the initial line and onto one or more subsequent lines.
+.sp
+Patterns used with \fB-M\fP may usefully contain literal newline characters and
+internal occurrences of ^ and $ characters, because in multiline mode these can
+match at internal newlines. Because \fBpcre2grep\fP is scanning multiple lines,
+the \eZ and \ez assertions match only at the end of the last line in the file.
+The \eA assertion matches at the start of the first line of a match. This can
+be any line in the file; it is not anchored to the first line.
+.sp
+The output for a successful match may consist of more than one line. The first
+line is the line in which the match started, and the last line is the line in
+which the match ended. If the matched string ends with a newline sequence, the
+output ends at the end of that line. If \fB-v\fP is set, none of the lines in a
+multi-line match are output. Once a match has been handled, scanning restarts
+at the beginning of the line after the one in which the match ended.
 .sp
 The newline sequence that separates multiple lines must be matched as part of
 the pattern. For example, to find the phrase "regular expression" in a file
@@ -1006,6 +1013,6 @@ Cambridge, England.
 .rs
 .sp
 .nf
-Last updated: 20 November 2023
+Last updated: 22 December 2023
 Copyright (c) 1997-2023 University of Cambridge.
 .fi