From 5be3f744b4005f71f372929f883264eb59f729bb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fernando=20Apestegu=C3=ADa?= <fernape@FreeBSD.org>
Date: Thu, 19 Nov 2020 18:58:15 +0000
Subject: [PATCH] grep(1): Add more EXAMPLES

* Add more EXAMPLES covering flags: -A, -B, -c, -f, -i, -H, -l, -q, -R, -w
* While here, change existing wording to use the imperative (remove "To
  find")
* Reword first example to be consistent with how grep(1) understand
  words (-w)

Approved by:	manpages (bcr@)
Differential Revision:		https://reviews.freebsd.org/D27264
---
 usr.bin/grep/grep.1 | 65 +++++++++++++++++++++++++++++++++++++++------
 1 file changed, 57 insertions(+), 8 deletions(-)

diff --git a/usr.bin/grep/grep.1 b/usr.bin/grep/grep.1
index b6f6e6f31d22..d3b30828c821 100644
--- a/usr.bin/grep/grep.1
+++ b/usr.bin/grep/grep.1
@@ -30,7 +30,7 @@
 .\"
 .\"	@(#)grep.1	8.3 (Berkeley) 4/18/94
 .\"
-.Dd August 7, 2020
+.Dd November 19, 2020
 .Dt GREP 1
 .Os
 .Sh NAME
@@ -456,13 +456,27 @@ An error occurred.
 .Sh EXAMPLES
 .Bl -dash
 .It
-To find all occurrences of the word
+Find all occurrences of the pattern
 .Sq patricia
 in a file:
 .Pp
 .Dl $ grep 'patricia' myfile
 .It
-To find all occurrences of the pattern
+Same as above but looking only for complete words:
+.Pp
+.Dl $ grep -w 'patricia' myfile
+.It
+Count occurrences of the exact pattern
+.Sq FOO
+:
+.Pp
+.Dl $ grep -c FOO myfile
+.It
+Same as above but ignoring case:
+.Pp
+.Dl $ grep -c -i FOO myfile
+.It
+Find all occurrences of the pattern
 .Ql .Pp
 at the beginning of a line:
 .Pp
@@ -480,20 +494,55 @@ escapes the
 .Ql \&. ,
 which would otherwise match any character.
 .It
-To find all lines in a file which do not contain the words
+Find all lines in a file which do not contain the words
 .Sq foo
 or
 .Sq bar :
 .Pp
 .Dl $ grep -v -e 'foo' -e 'bar' myfile
 .It
-A simple example of an extended regular expression:
+Peruse the file
+.Sq calendar
+looking for either 19, 20, or 25 using extended regular expressions:
 .Pp
 .Dl $ egrep '19|20|25' calendar
+.It
+Show matching lines and the name of the
+.Sq *.h
+files which contain the pattern
+.Sq FIXME .
+Do the search recursively from the
+.Pa /usr/src/sys/arm
+directory
 .Pp
-Peruses the file
-.Sq calendar
-looking for either 19, 20, or 25.
+.Dl $ grep -H -R FIXME --include=*.h /usr/src/sys/arm/
+.It
+Same as above but show only the name of the matching file:
+.Pp
+.Dl $ grep -l -R FIXME --include=*.h /usr/src/sys/arm/
+.It
+Show lines containing the text
+.Sq foo .
+The matching part of the output is colored and every line is prefixed with
+the line number and the offset in the file for those lines that matched.
+.Pp
+.Dl $ grep -b --colour -n foo myfile
+.It
+Show lines that match the extended regular expression patterns read from the
+standard input:
+.Pp
+.Dl $ echo -e 'Free\enBSD\enAll.*reserved' | grep -E -f - myfile
+.It
+Show lines from the output of the
+.Xr pciconf 8
+command matching the specified extended regular expression along with
+three lines of leading context and one line of trailing context:
+.Pp
+.Dl $ pciconf -lv | grep -B3 -A1 -E 'class.*=.*storage'
+.It
+Suppress any output and use the exit status to show an appropriate message:
+.Pp
+.Dl $ grep -q foo myfile && echo File matches
 .El
 .Sh SEE ALSO
 .Xr ed 1 ,