Subject: Re: bug#20088: -a changes whether a match is found

From: Paul Eggert <[email-masked]>
Date: Wed, 11 Mar 2015 11:02:42 -0700

On 03/11/2015 10:38 AM, Jim Meyering wrote:
> --text (-a) is documented to change only the output, not grep's exit status.
>

It is documented, albeit too tersely.  I tried to improve it by 
installing the attached.
>From c71daa9998680001ae52b6a3f3e7889b2d1eb512 Mon Sep 17 00:00:00 2001
From: Paul Eggert <[email-masked]>
Date: Wed, 11 Mar 2015 10:59:27 -0700
Subject: [PATCH] doc: clarify how -a matches

* doc/grep.in.1, doc/grep.texi (File and Directory Selection):
Give an example of how non-text bytes affect pattern matching in
binary files.
Fixes: bug#20080
---
 doc/grep.in.1 | 6 ++++++
 doc/grep.texi | 6 ++++--
 2 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/doc/grep.in.1 b/doc/grep.in.1
index dfd8288..2b513a8 100644
--- a/doc/grep.in.1
+++ b/doc/grep.in.1
@@ -383,6 +383,12 @@ is
 processes a binary file as if it were text; this is equivalent to the
 .B \-a
 option.
+When processing binary data,
+.B grep
+may treat non-text bytes as line terminators; for example, the pattern
+.RB ' . '\&
+(period) might not match a null byte, as the null byte might be
+treated as a line terminator.
 .I Warning:
 .B "grep \-\^\-binary\-files=text"
 might output binary garbage,
diff --git a/doc/grep.texi b/doc/grep.texi
index 7738677..18a1102 100644
--- a/doc/grep.texi
+++ b/doc/grep.texi
@@ -605,8 +605,10 @@ By default, @var{type} is @samp{binary},
 and @command{grep} normally outputs either
 a one-line message saying that a binary file matches,
 or no message if there is no match.
-When matching binary data, @command{grep} may treat non-text
-bytes as line terminators.
+When processing binary data, @command{grep} may treat non-text bytes
+as line terminators; for example, the pattern @samp{.} (period) might
+not match a null byte, as the null byte might be treated as a line
+terminator even without the @option{-z} (@option{--null-data}) option.
 
 If @var{type} is @samp{without-match},
 @command{grep} assumes that a binary file does not match;
-- 
2.1.0