Update pcre2grep documentation to give more details of -M matching.

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

1 files changed, 84 insertions, 62 deletions

diff --git a/doc/pcre2grep.1 b/doc/pcre2grep.1
index 45a8cfa..028a91e 100644
--- a/doc/pcre2grep.1
+++ b/doc/pcre2grep.1
@@ -1,4 +1,4 @@
-.TH PCRE2GREP 1 "23 November 2014" "PCRE2 10.00"
+.TH PCRE2GREP 1 "03 January 2015" "PCRE2 10.00"
 .SH NAME
 pcre2grep - a grep with Perl-compatible regular expressions.
 .SH SYNOPSIS
@@ -41,21 +41,22 @@ If no files are specified, \fBpcre2grep\fP reads the standard input. The
 standard input can also be referenced by a name consisting of a single hyphen.
 For example:
 .sp
-  pcre2grep some-pattern /file1 - /file3
+  pcre2grep some-pattern file1 - file3
 .sp
-By default, 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. In particular, the \fB-M\fP option makes it
-possible to search for patterns that span line boundaries. What defines a line
-boundary is controlled by the \fB-N\fP (\fB--newline\fP) option.
+Input files are searched line by line. By default, 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. In
+particular, 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.
 .P
 The amount of memory used for buffering files that are being scanned is
 controlled by a parameter that can be set by the \fB--buffer-size\fP option.
-The default value for this parameter is specified when \fBpcre2grep\fP is built,
-with the default default being 20K. A block of memory three times this size is
-used (to allow for buffering "before" and "after" lines). An error occurs if a
-line overflows the buffer.
+The default value for this parameter is specified when \fBpcre2grep\fP is
+built, with the default default being 20K. A block of memory three times this
+size is used (to allow for buffering "before" and "after" lines). An error
+occurs if a line overflows the buffer.
 .P
 Patterns can be no longer than 8K or BUFSIZ bytes, whichever is the greater.
 BUFSIZ is defined in \fB<stdio.h>\fP. When there is more than one pattern
@@ -122,10 +123,10 @@ to signify multiplication by 1024 or 1024*1024 respectively.
 \fB--\fP
 This terminates the list of options. It is useful if the next item on the
 command line starts with a hyphen but is not an option. This allows for the
-processing of patterns and filenames that start with hyphens.
+processing of patterns and file names that start with hyphens.
 .TP
 \fB-A\fP \fInumber\fP, \fB--after-context=\fP\fInumber\fP
-Output \fInumber\fP lines of context after each matching line. If filenames
+Output \fInumber\fP lines of context after each matching line. If file names
 and/or line numbers are being output, a hyphen separator is used instead of a
 colon for the context lines. A line containing "--" is output between each
 group of lines, unless they are in fact contiguous in the input file. The value
@@ -137,7 +138,7 @@ Treat binary files as text. This is equivalent to
 \fB--binary-files\fP=\fItext\fP.
 .TP
 \fB-B\fP \fInumber\fP, \fB--before-context=\fP\fInumber\fP
-Output \fInumber\fP lines of context before each matching line. If filenames
+Output \fInumber\fP lines of context before each matching line. If file names
 and/or line numbers are being output, a hyphen separator is used instead of a
 colon for the context lines. A line containing "--" is output between each
 group of lines, unless they are in fact contiguous in the input file. The value
@@ -153,7 +154,8 @@ processed in the same way as any other file. In this case, when a match
 succeeds, the output may be binary garbage, which can have nasty effects if
 sent to a terminal. If the word is "without-match", which is equivalent to the
 \fB-I\fP option, binary files are not processed at all; they are assumed not to
-be of interest.
+be of interest and are skipped without causing any output or affecting the
+return code.
 .TP
 \fB--buffer-size=\fP\fInumber\fP
 Set the parameter that controls how much memory is used for buffering files
@@ -164,10 +166,14 @@ Output \fInumber\fP lines of context both before and after each matching line.
 This is equivalent to setting both \fB-A\fP and \fB-B\fP to the same value.
 .TP
 \fB-c\fP, \fB--count\fP
-Do not output individual lines from the files that are being scanned; instead
-output the number of lines that would otherwise have been shown. If no lines
-are selected, the number zero is output. If several files are are being
-scanned, a count is output for each of them. However, if the
+Do not output lines from the files that are being scanned; instead output the
+number of matches (or non-matches if \fB-v\fP is used) that would otherwise
+have caused lines to be shown. By default, this count is the same as the number
+of suppressed lines, but if the \fB-M\fP (multiline) option is used (without
+\fB-v\fP), there may be more suppressed lines than the number of matches.
+.sp
+If no lines are selected, the number zero is output. If several files are are
+being scanned, a count is output for each of them. However, if the
 \fB--files-with-matches\fP option is also used, only those files whose counts
 are greater than zero are listed. When \fB-c\fP is used, the \fB-A\fP,
 \fB-B\fP, and \fB-C\fP options are ignored.
@@ -229,10 +235,10 @@ of the line that matched.
 Files (but not directories) whose names match the pattern are skipped without
 being processed. This applies to all files, whether listed on the command line,
 obtained from \fB--file-list\fP, or by scanning a directory. The pattern is a
-PCRE2 regular expression, and is matched against the final component of the file
-name, not the entire path. The \fB-F\fP, \fB-w\fP, and \fB-x\fP options do not
-apply to this pattern. The option may be given any number of times in order to
-specify multiple patterns. If a file name matches both an \fB--include\fP
+PCRE2 regular expression, and is matched against the final component of the
+file name, not the entire path. The \fB-F\fP, \fB-w\fP, and \fB-x\fP options do
+not apply to this pattern. The option may be given any number of times in order
+to specify multiple patterns. If a file name matches both an \fB--include\fP
 and an \fB--exclude\fP pattern, it is excluded. There is no short form for this
 option.
 .TP
@@ -276,7 +282,7 @@ also the comments about multiple patterns versus a single pattern with
 alternatives in the description of \fB-e\fP above.
 .sp
 If this option is given more than once, all the specified files are
-read. A data line is output if any of the patterns match it. A filename can
+read. A data line is output if any of the patterns match it. A file name can
 be given as "-" to refer to the standard input. When \fB-f\fP is used, patterns
 specified on the command line using \fB-e\fP may also be present; they are
 tested before the file's patterns. However, no other pattern is taken from the
@@ -286,7 +292,7 @@ command line; all arguments are treated as the names of paths to be searched.
 Read a list of files and/or directories that are to be scanned from the given
 file, one per line. Trailing white space is removed from each line, and blank
 lines are ignored. These paths are processed before any that are listed on the
-command line. The filename can be given as "-" to refer to the standard input.
+command line. The file name can be given as "-" to refer to the standard input.
 If \fB--file\fP and \fB--file-list\fP are both specified as "-", patterns are
 read first. This is useful only when the standard input is a terminal, from
 which further lines (the list of files) can be read after an end-of-file
@@ -302,16 +308,17 @@ shown separately. This option is mutually exclusive with \fB--line-offsets\fP
 and \fB--only-matching\fP.
 .TP
 \fB-H\fP, \fB--with-filename\fP
-Force the inclusion of the filename at the start of output lines when searching
-a single file. By default, the filename is not shown in this case. For matching
-lines, the filename is followed by a colon; for context lines, a hyphen
-separator is used. If a line number is also being output, it follows the file
-name.
+Force the inclusion of the file name at the start of output lines when
+searching a single file. By default, the file name is not shown in this case.
+For matching lines, the file name is followed by a colon; for context lines, a
+hyphen separator is used. If a line number is also being output, it follows the
+file name. When the \fB-M\fP option causes a pattern to match more than one
+line, only the first is preceded by the file name.
 .TP
 \fB-h\fP, \fB--no-filename\fP
-Suppress the output filenames when searching multiple files. By default,
-filenames are shown when multiple files are searched. For matching lines, the
-filename is followed by a colon; for context lines, a hyphen separator is used.
+Suppress the output file names when searching multiple files. By default,
+file names are shown when multiple files are searched. For matching lines, the
+file name is followed by a colon; for context lines, a hyphen separator is used.
 If a line number is also being output, it follows the file name.
 .TP
 \fB--help\fP
@@ -320,7 +327,7 @@ type support, and then exit. Anything else on the command line is
 ignored.
 .TP
 \fB-I\fP
-Treat binary files as never matching. This is equivalent to
+Ignore binary files. This is equivalent to
 \fB--binary-files\fP=\fIwithout-match\fP.
 .TP
 \fB-i\fP, \fB--ignore-case\fP
@@ -349,8 +356,8 @@ If any \fB--include-dir\fP patterns are specified, the only directories that
 are processed are those that match one of the patterns (and do not match an
 \fB--exclude-dir\fP pattern). This applies to all directories, whether listed
 on the command line, obtained from \fB--file-list\fP, or by scanning a parent
-directory. The pattern is a PCRE2 regular expression, and is matched against the
-final component of the directory name, not the entire path. The \fB-F\fP,
+directory. The pattern is a PCRE2 regular expression, and is matched against
+the final component of the directory name, not the entire path. The \fB-F\fP,
 \fB-w\fP, and \fB-x\fP options do not apply to this pattern. The option may be
 given any number of times. If a directory matches both \fB--include-dir\fP and
 \fB--exclude-dir\fP, it is excluded. There is no short form for this option.
@@ -381,8 +388,8 @@ unless \fBpcre2grep\fP can determine that it is reading from a terminal (which
 is currently possible only in Unix-like environments). Output to terminal is
 normally automatically flushed by the operating system. This option can be
 useful when the input or output is attached to a pipe and you do not want
-\fBpcre2grep\fP to buffer up large amounts of data. However, its use will affect
-performance, and the \fB-M\fP (multiline) option ceases to work.
+\fBpcre2grep\fP to buffer up large amounts of data. However, its use will
+affect performance, and the \fB-M\fP (multiline) option ceases to work.
 .TP
 \fB--line-offsets\fP
 Instead of showing lines or parts of lines that match, show each match as a
@@ -429,17 +436,31 @@ when the PCRE2 library is compiled, with the default default being 10 million.
 Allow patterns to match more than one line. When this option is given, patterns
 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 last of which is the one in which the match ended. If the matched
-string ends with a newline sequence the output ends at the end of that line.
+one line. The first is the line in which the match started, and the last 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.
 .sp
 When this option is set, the PCRE2 library is called in "multiline" mode.
+However, \fBpcre2grep\fP still processes the input line by line. The difference
+is that a matched string may extend past the end of a line and continue on
+one or more subsequent lines. The newline sequence must be matched as part of
+the pattern. For example, to find the phrase "regular expression" in a file
+where "regular" might be at the end of a line and "expression" at the start of
+the next line, you could use this command:
+.sp
+  pcre2grep -M 'regular\es+expression' <file>
+.sp
+The \es escape sequence matches any white space character, including newlines,
+and is followed by + so as to match trailing white space on the first line as
+well as possibly handling a two-character newline sequence.
+.sp
 There is a limit to the number of lines that can be matched, imposed by the way
 that \fBpcre2grep\fP buffers the input file as it scans it. However,
-\fBpcre2grep\fP ensures that at least 8K characters or the rest of the document
+\fBpcre2grep\fP ensures that at least 8K characters or the rest of the file
 (whichever is the shorter) are available for forward matching, and similarly
 the previous 8K characters (or all the previous characters, if fewer than 8K)
-are guaranteed to be available for lookbehind assertions. This option does not
-work when input is read line by line (see \fP--line-buffered\fP.)
+are guaranteed to be available for lookbehind assertions. The \fB-M\fP option
+does not work when input is read line by line (see \fP--line-buffered\fP.)
 .TP
 \fB-N\fP \fInewline-type\fP, \fB--newline\fP=\fInewline-type\fP
 The PCRE2 library supports five different conventions for indicating
@@ -455,9 +476,9 @@ When the PCRE2 library is built, a default line-ending sequence is specified.
 This is normally the standard sequence for the operating system. Unless
 otherwise specified by this option, \fBpcre2grep\fP uses the library's default.
 The possible values for this option are CR, LF, CRLF, ANYCRLF, or ANY. This
-makes it possible to use \fBpcre2grep\fP to scan files that have come from other
-environments without having to modify their line endings. If the data that is
-being scanned does not agree with the convention set by this option,
+makes it possible to use \fBpcre2grep\fP to scan files that have come from
+other environments without having to modify their line endings. If the data
+that is being scanned does not agree with the convention set by this option,
 \fBpcre2grep\fP may behave in strange ways. Note that this option does not
 apply to files specified by the \fB-f\fP, \fB--exclude-from\fP, or
 \fB--include-from\fP options, which are expected to use the operating system's
@@ -465,9 +486,10 @@ standard newline sequence.
 .TP
 \fB-n\fP, \fB--line-number\fP
 Precede each output line by its line number in the file, followed by a colon
-for matching lines or a hyphen for context lines. If the filename is also being
-output, it precedes the line number. This option is forced if
-\fB--line-offsets\fP is used.
+for matching lines or a hyphen for context lines. If the file name is also
+being output, it precedes the line number. When the \fB-M\fP option causes a
+pattern to match more than one line, only the first is preceded by its line
+number. This option is forced if \fB--line-offsets\fP is used.
 .TP
 \fB--no-jit\fP
 If the PCRE2 library is built with support for just-in-time compiling (which
@@ -495,7 +517,7 @@ without an argument (see above), if an argument is present, it must be given in
 the same shell item, for example, -o3 or --only-matching=2. The comments given
 for the non-argument case above also apply to this case. If the specified
 capturing parentheses do not exist in the pattern, or were not set in the
-match, nothing is output unless the file name or line number are being printed.
+match, nothing is output unless the file name or line number are being output.
 .sp
 If this option is given multiple times, multiple substrings are output, in the
 order the options are given. For example, -o3 -o1 -o3 causes the substrings
@@ -549,10 +571,10 @@ specified by any of the \fB--include\fP or \fB--exclude\fP options.
 \fB-x\fP, \fB--line-regex\fP, \fB--line-regexp\fP
 Force the patterns to be anchored (each must start matching at the beginning of
 a line) and in addition, require them to match entire lines. This is equivalent
-to having ^ and $ characters at the start and end of each alternative branch in
-every pattern. This option applies only to the patterns that are matched
-against the contents of files; it does not apply to patterns specified by any
-of the \fB--include\fP or \fB--exclude\fP options.
+to having ^ and $ characters at the start and end of each alternative top-level
+branch in every pattern. This option applies only to the patterns that are
+matched against the contents of files; it does not apply to patterns specified
+by any of the \fB--include\fP or \fB--exclude\fP options.
 .
 .
 .SH "ENVIRONMENT VARIABLES"
@@ -596,7 +618,7 @@ Although most of the common options work the same way, a few are different in
 \fBpcre2grep\fP. For example, the \fB--include\fP option's argument is a glob
 for GNU \fBgrep\fP, but a regular expression for \fBpcre2grep\fP. If both the
 \fB-c\fP and \fB-l\fP options are given, GNU grep lists only file names,
-without counts, but \fBpcre2grep\fP gives the counts.
+without counts, but \fBpcre2grep\fP gives the counts as well.
 .
 .
 .SH "OPTIONS WITH DATA"
@@ -642,9 +664,9 @@ in these circumstances. If this happens, \fBpcre2grep\fP outputs an error
 message and the line that caused the problem to the standard error stream. If
 there are more than 20 such errors, \fBpcre2grep\fP gives up.
 .P
-The \fB--match-limit\fP option of \fBpcre2grep\fP can be used to set the overall
-resource limit; there is a second option called \fB--recursion-limit\fP that
-sets a limit on the amount of memory (usually stack) that is used (see the
+The \fB--match-limit\fP option of \fBpcre2grep\fP can be used to set the
+overall resource limit; there is a second option called \fB--recursion-limit\fP
+that sets a limit on the amount of memory (usually stack) that is used (see the
 discussion of these options above).
 .
 .
@@ -661,7 +683,7 @@ affect the return code.
 .SH "SEE ALSO"
 .rs
 .sp
-\fBpcre2pattern\fP(3), \fBpcre2syntax\fP(3), \fBpcre2test\fP(1).
+\fBpcre2pattern\fP(3), \fBpcre2syntax\fP(3).
 .
 .
 .SH AUTHOR
@@ -678,6 +700,6 @@ Cambridge, England.
 .rs
 .sp
 .nf
-Last updated: 23 November 2014
-Copyright (c) 1997-2014 University of Cambridge.
+Last updated: 03 January 2015
+Copyright (c) 1997-2015 University of Cambridge.
 .fi