various fixes to make this page a bit clearer and hopefully a bit

more helpful;

this includes some ideas/fixes from otto and jared;

2 files changed, 214 insertions, 131 deletions

diff --git a/usr.bin/grep/grep.1 b/usr.bin/grep/grep.1
index e7523ebeda6..6e1b1f13890 100644
--- a/usr.bin/grep/grep.1
+++ b/usr.bin/grep/grep.1
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: grep.1,v 1.26 2004/04/17 20:10:55 jmc Exp $
+.\"	$OpenBSD: grep.1,v 1.27 2004/09/28 20:51:15 jmc Exp $
 .\" Copyright (c) 1980, 1990, 1993
 .\"	The Regents of the University of California.  All rights reserved.
 .\"
@@ -32,58 +32,69 @@
 .Dt GREP 1
 .Os
 .Sh NAME
-.Nm grep, egrep, fgrep, zgrep, zegrep, zfgrep
+.Nm grep , egrep , fgrep ,
+.Nm zgrep , zegrep , zfgrep
 .Nd file pattern searcher
 .Sh SYNOPSIS
 .Nm grep
-.Op Fl AB Ar num
-.Op Fl CEFGHILPRSUVZabchilnoqsvwx
-.Op Fl -context Ns Op = Ns Ar num
-.Op Fl -binary-files Ns = Ns Ar value
-.Op Fl -line-buffered
+.Bk -words
+.Op Fl abcEFGHhIiLlnoPqRSsUVvwxZ
+.Op Fl A Ar num
+.Op Fl B Ar num
+.Op Fl C Ns Op Ar num
 .Op Fl e Ar pattern
 .Op Fl f Ar file
+.Op Fl -binary-files Ns = Ns Ar value
+.Op Fl -context Ns Op = Ns Ar num
+.Op Fl -line-buffered
 .Op Ar pattern
 .Op Ar
+.Ek
 .Sh DESCRIPTION
 The
 .Nm grep
-utilities search the given input files selecting lines that match one
-or more patterns.
-By default, a pattern matches an input line if any regular expression
-(RE) in the pattern matches the input line without its trailing
-newline.
+utility searches any given input files,
+selecting lines that match one or more patterns.
+By default, a pattern matches an input line if the regular expression
+(RE) in the pattern matches the input line
+without its trailing newline.
 An empty expression matches every line.
 Each input line that matches at least one of the patterns is written
 to the standard output.
 .Pp
-The
 .Nm grep
-utility is used for simple patterns and
-.Xr ex 1
+is used for simple patterns and
+.Xr ex 1 -
 or
-.Xr ed 1
-style regular expressions.
-The
+.Xr ed 1 -style
+regular expressions.
 .Nm egrep
-utility can handle extended regular expressions and multi-line
-patterns.
-The
+can handle extended regular expressions;
+for a discussion of extended regular expressions, see
+.Xr re_format 7 ;
+for a list of extended regular expression special characters, see
+.Sx EXTENDED REGULAR EXPRESSIONS ,
+below.
 .Nm fgrep
-utility is quick but can handle only fixed patterns consisting of one
-or more lines, allowing any of the pattern lines to match a portion of
-the input.
-The
+is quicker than both
+.Nm grep
+and
+.Nm egrep ,
+but can only handle fixed patterns
+(i.e. it does not interpret regular expressions).
+Patterns may consist of one or more lines,
+allowing any of the pattern lines to match a portion of the input.
+.Pp
 .Nm zgrep ,
 .Nm zegrep ,
 and
 .Nm zfgrep
-utilities act like
+act like
 .Nm grep ,
 .Nm egrep ,
 and
-.Nm fgrep
-respectively but accept input files compressed with the
+.Nm fgrep ,
+respectively, but accept input files compressed with the
 .Xr compress 1
 or
 .Xr gzip 1
@@ -95,89 +106,104 @@ The following options are available:
 Print
 .Ar num
 lines of trailing context after each match.
+See also the
+.Fl B
+and
+.Fl C
+options.
+.It Fl a
+Treat all files as ASCII text.
 .It Fl B Ar num
 Print
 .Ar num
 lines of leading context before each match.
-.It Fl C
-Print 2 lines of leading and trailing context after each match.
-Equivalent to
+See also the
+.Fl A
+and
+.Fl C
+options.
+.It Fl b
+The offset in bytes of a matched pattern is
+displayed in front of the respective matched line.
+.It Fl C Ns Op Ar num
+Print
+.Ar num
+lines of leading and trailing context surrounding each match.
+The default is 2 and is equivalent to
 .Fl A
 .Ar 2
 .Fl B
 .Ar 2 .
+Note:
+no whitespace may be given between the option and its argument.
+.It Fl c
+Only a count of selected lines is written to standard output.
 .It Fl E
-Force
+Interpret
+.Ar pattern
+as an extended regular expression
+(i.e. force
 .Nm grep
 to behave as
-.Nm egrep .
+.Nm egrep ) .
+.It Fl e Ar pattern
+Specify a pattern used during the search of the input:
+an input line is selected if it matches any of the specified patterns.
+This option is most useful when multiple
+.Fl e
+options are used to specify multiple patterns,
+or when a pattern begins with a dash
+.Pq Sq - .
 .It Fl F
-Force
+Interpret
+.Ar pattern
+as a set of fixed strings
+(i.e. force
 .Nm grep
 to behave as
-.Nm fgrep .
+.Nm fgrep ) .
+.It Fl f Ar file
+Read one or more newline separated patterns from
+.Ar file .
+Newlines are not considered part of a pattern.
 .It Fl G
-Force
+Interpret
+.Ar pattern
+as a basic regular expression
+(i.e. force
 .Nm grep
-to behave as
-.Nm grep .
+to behave as traditional
+.Nm grep ) .
 .It Fl H
 If
 .Fl R
 is specified, follow symbolic links only if they were explicitly listed
 on the command line.
+The default is not to follow symbolic links.
+.It Fl h
+Never print filename headers
+.Pq i.e. filenames
+with output lines.
 .It Fl I
 Ignore binary files.
+.It Fl i
+Perform case insensitive matching.
+By default,
+.Nm grep
+is case sensitive.
 .It Fl L
 Only the names of files not containing selected lines are written to
 standard output.
 Pathnames are listed once per file searched.
 If the standard input is searched, the pathname
-.Sq Fl
+.Sq -
 is written.
-.It Fl P
-If
-.Fl R
-is specified, no symbolic links are followed.
-.It Fl R
-Recursively search subdirectories listed.
-.It Fl S
-If
-.Fl R
-is specified, all symbolic links are followed.
-.It Fl U
-Search binary files, but do not attempt to print them.
-.It Fl V
-Display version information.
-.It Fl Z
-Force
-.Nm grep
-to behave as
-.Nm zgrep .
-.It Fl a
-Treat all files as text.
-.It Fl b
-The offset in bytes of a matched pattern is
-displayed in front of the respective matched line.
-.It Fl c
-Only a count of selected lines is written to standard output.
-.It Fl e Ar expression
-Specify a pattern used during the search of the input.
-Multiple
-.Fl e
-options can be used to specify multiple patterns; an input line is
-selected if it matches any of the specified patterns.
-.It Fl f Ar pattern_file
-Read one or more newline separated patterns from
-.Ar pattern_file .
-Newlines are not considered part of a pattern.
-.It Fl h
-Never print filename headers with output lines.
-.It Fl i
-Perform case insensitive matching.
 .It Fl l
 Only the names of files containing selected lines are written to
 standard output.
+.Nm grep
+will only search a file until a match has been found,
+making searches potentially less expensive.
 Pathnames are listed once per file searched.
 If the standard input is searched, the pathname
 .Sq -
@@ -188,48 +214,78 @@ starting at line 1.
 The line number counter is reset for each file processed.
 This option is ignored if
 .Fl c ,
+.Fl L ,
 .Fl l ,
+.Fl q ,
 or
-.Fl q
+.Fl v
 is
 specified.
 .It Fl o
 Always print filename headers with output lines.
+.It Fl P
+If
+.Fl R
+is specified, no symbolic links are followed.
+This is the default.
 .It Fl q
-Suppress normal output.
+Quiet mode:
+suppress normal output.
+.Nm grep
+will only search a file until a match has been found,
+making searches potentially less expensive.
+.It Fl R
+Recursively search subdirectories listed.
+.It Fl S
+If
+.Fl R
+is specified, all symbolic links are followed.
+The default is not to follow symbolic links.
 .It Fl s
 Silent mode.
-Nonexistent and unreadable files are ignored.
+Nonexistent and unreadable files are ignored
+(i.e. their error messages are suppressed).
+.It Fl U
+Search binary files, but do not attempt to print them.
+.It Fl V
+Display version information.
+All other options are ignored.
 .It Fl v
 Selected lines are those
 .Em not
 matching any of the specified patterns.
 .It Fl w
-The expression is searched for as a word (as if surrounded by `[[:<:]]'
-and `[[:>:]]', see
+The expression is searched for as a word (as if surrounded by
+.Sq [[:<:]]
+and
+.Sq [[:>:]] ;
+see
 .Xr re_format 7 ) .
 .It Fl x
 Only input lines selected against an entire fixed string or regular
 expression are considered to be matching lines.
-.Sm off
-.It Fl Fl context Op = Ar num
-.Sm on
-Print
-.Ar num
-lines of leading and trailing context.
-Default is 2.
-.Sm off
-.It Fl Fl binary-files No = Ar value
-.Sm on
+.It Fl Z
+Force
+.Nm grep
+to behave as
+.Nm zgrep .
+.It Fl Fl binary-files Ns = Ns Ar value
 Controls searching and printing of binary files.
 Options are
 .Ar binary ,
-the default, search binary files but do not print them;
-.Ar without-match ,
+the default: search binary files but do not print them;
+.Ar without-match :
 do not search binary files;
 and
-.Ar text ,
+.Ar text :
 treat all files as text.
+.Sm off
+.It Fl Fl context Op = Ar num
+.Sm on
+Print
+.Ar num
+lines of leading and trailing context.
+The default is 2.
 .It Fl Fl line-buffered
 Force output to be line buffered.
 By default, output is line buffered when standard output is a terminal
@@ -247,7 +303,7 @@ utility exits with one of the following values:
 One or more lines were selected.
 .It Li 1
 No lines were selected.
-.It Li >1
+.It Li \*(Gt1
 An error occurred.
 .El
 .Sh EXTENDED REGULAR EXPRESSIONS
@@ -255,71 +311,98 @@ The following characters are interpreted by
 .Nm egrep :
 .Pp
 .Bl -tag -width flag -compact
-.It Cm \&$
-Align the match from the end of the line.
-.It Cm \&^
+.It Cm ^
 Align the match from the beginning of the line.
+.It Cm $
+Align the match from the end of the line.
 .It Cm \&|
 Add another pattern (see example below).
+.It Cm \&.
+Match any single character.
 .It Cm \&?
 Match 1 or less sequential repetitions of the pattern.
-.It Cm \&+
+.It Cm +
 Match 1 or more sequential repetitions of the pattern.
-.It Cm \&*
+.It Cm *
 Match 0 or more sequential repetitions of the pattern.
-.It Cm \&{}
+.It Cm {}
 Match specified number of sequential repetitions of the pattern.
-.It Cm \&[]
-Match any single character or range of characters
-enclosed in the brackets.
-.It Cm \&\e
+.It Cm []
+Match any characters enclosed in the brackets.
+.It Cm ()
+Delimits a subexpression.
+.It Cm \e
 Escape special characters which have meaning to
-.Nm egrep ,
-the set of `$.^[]|?+*{}()\e'.
+.Nm egrep .
 .El
 .Sh EXAMPLES
-To find all occurrences of the word patricia in a file:
+To find all occurrences of the word
+.Sq patricia
+in a file:
 .Pp
-.Dl grep patricia myfile
+.Dl $ grep 'patricia' myfile
 .Pp
 To find all occurrences of the pattern
-.Ql \&.Pp
+.Ql .Pp
 at the beginning of a line:
 .Pp
-.Dl grep '^\e.Pp'
+.Dl $ grep '^\e.Pp' myfile
 .Pp
 The apostrophes ensure the entire expression is evaluated by
 .Nm grep
-instead of by the
-user's shell.
+instead of by the user's shell.
 The caret
-.Ql \&^
+.Ql ^
 matches the null string at the beginning of a line,
 and the
-.Ql \&\e
+.Ql \e
 escapes the
-.Ql \&.
+.Ql \&. ,
 which would otherwise match any character.
 .Pp
-To find all lines in a file which do not contain the words foo or bar:
+To 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
+.Dl $ grep -v -e 'foo' -e 'bar' myfile
 .Pp
 A simple example of an extended regular expression:
 .Pp
-.Dl egrep '19|20|25' calendar
+.Dl $ egrep '19|20|25' calendar
 .Pp
-Peruses the file calendar looking for either 19, 20
-or 25.
+Peruses the file
+.Sq calendar
+looking for either 19, 20, or 25.
 .Sh SEE ALSO
 .Xr ed 1 ,
 .Xr ex 1 ,
+.Xr gzip 1 ,
 .Xr sed 1 ,
 .Xr regex 3 ,
-.Xr regexp 3 ,
 .Xr re_format 7
+.Sh STANDARDS
+The
+.Nm grep
+utility is compliant with the
+.St -p1003.1-2003
+specification.
+.Pp
+The flags
+.Op Fl AaBbCGHhILoPRSUVwZ
+are extensions to that specification.
+.Pp
+All long options are provided for compatibility with
+GNU versions of this utility.
+.Pp
+Historic versions of the
+.Nm grep
+utility also supported the flags
+.Op Fl ruy .
+This implementation supports those options;
+however, their use is strongly discouraged.
 .Sh HISTORY
 The
 .Nm grep
-command appeared in
+command first appeared in
 .At v6 .
diff --git a/usr.bin/grep/grep.c b/usr.bin/grep/grep.c
index 8ce5a0cb96d..3f96ea62a4a 100644
--- a/usr.bin/grep/grep.c
+++ b/usr.bin/grep/grep.c
@@ -1,4 +1,4 @@
-/*	$OpenBSD: grep.c,v 1.29 2004/08/05 21:47:33 deraadt Exp $	*/
+/*	$OpenBSD: grep.c,v 1.30 2004/09/28 20:51:15 jmc Exp $	*/
 
 /*-
  * Copyright (c) 1999 James Howard and Dag-Erling Coïdan Smørgrav
@@ -107,12 +107,12 @@ usage(void)
 {
 	fprintf(stderr,
 #ifdef NOZ
-	    "usage: %s [-AB num] [-CEFGHILPRSUVabchilnoqsvwx]\n"
+	    "usage: %s [-abcEFGHhIiLlnoPqRSsUVvwx] [-A num] [-B num] [-C[num]]\n"
 #else
-	    "usage: %s [-AB num] [-CEFGHILPRSUVZabchilnoqsvwx]\n"
+	    "usage: %s [-abcEFGHhIiLlnoPqRSsUVvwxZ] [-A num] [-B num] [-C[num]]\n"
 #endif
-	    "\t[--context[=num]] [--binary-files=value] [--line-buffered]\n"
-	    "\t[-e pattern] [-f file] [pattern] [file ...]\n", __progname);
+	    "\t[-e pattern] [-f file] [--binary-files=value] [--context[=num]]\n"
+	    "\t[--line-buffered] [pattern] [file ...]\n", __progname);
 	exit(2);
 }