svn commit: r338122 - head/usr.bin/grep
Mateusz Piotrowski
0mp at FreeBSD.org
Mon Aug 20 22:24:00 UTC 2018
Author: 0mp (ports committer)
Date: Mon Aug 20 22:23:59 2018
New Revision: 338122
URL: https://svnweb.freebsd.org/changeset/base/338122
Log:
Adjust formatting of grep and zgrep manual pages.
grep(1) changes:
- Pet mandoc & igor.
- Stylize the text more with macros when appropriate.
- Stylize equal signs in long options (e.g., "--color=auto") with
the "Cm" macro as suggested by mdoc(7).
- Add missing arguments to --exlude, --exclude-dir, --include and
--include-dir.
- Remove a duplicate entry for the --context flag.
- Use a list in the EXAMPLES sections to make it easier to tell
which paragraphs belong to which example.
- Cross reference zgrep(1).
zgrep(1) changes:
- Fix Nd.
- Split synopsis into paragraphs for readability.
- Cross reference bzip(1), grep(1) and xz(1).
Reviewed by: bcr
Approved by: mat (mentor)
Differential Revision: https://reviews.freebsd.org/D16779
Modified:
head/usr.bin/grep/grep.1
head/usr.bin/grep/zgrep.1
Modified: head/usr.bin/grep/grep.1
==============================================================================
--- head/usr.bin/grep/grep.1 Mon Aug 20 22:16:15 2018 (r338121)
+++ head/usr.bin/grep/grep.1 Mon Aug 20 22:23:59 2018 (r338122)
@@ -30,11 +30,14 @@
.\"
.\" @(#)grep.1 8.3 (Berkeley) 4/18/94
.\"
-.Dd May 7, 2018
+.Dd August 21, 2018
.Dt GREP 1
.Os
.Sh NAME
-.Nm grep , egrep , fgrep , rgrep ,
+.Nm grep ,
+.Nm egrep ,
+.Nm fgrep ,
+.Nm rgrep
.Nd file pattern searcher
.Sh SYNOPSIS
.Nm grep
@@ -45,10 +48,10 @@
.Op Fl C Ns Op Ar num
.Op Fl e Ar pattern
.Op Fl f Ar file
-.Op Fl Fl binary-files Ns = Ns Ar value
-.Op Fl Fl color Ns Op = Ns Ar when
-.Op Fl Fl colour Ns Op = Ns Ar when
-.Op Fl Fl context Ns Op = Ns Ar num
+.Op Fl Fl binary-files= Ns Ar value
+.Op Fl Fl color Ns Op Cm = Ns Ar when
+.Op Fl Fl colour Ns Op Cm = Ns Ar when
+.Op Fl Fl context Ns Op Cm = Ns Ar num
.Op Fl Fl label
.Op Fl Fl line-buffered
.Op Fl Fl null
@@ -83,13 +86,13 @@ is quicker than both
and
.Nm egrep ,
but can only handle fixed patterns
-(i.e. it does not interpret regular expressions).
+(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
The following options are available:
.Bl -tag -width indent
-.It Fl A Ar num , Fl Fl after-context Ns = Ns Ar num
+.It Fl A Ar num , Fl Fl after-context= Ns Ar num
Print
.Ar num
lines of trailing context after each match.
@@ -108,7 +111,7 @@ if files contain binary characters.
Use of this option forces
.Nm
to output lines matching the specified pattern.
-.It Fl B Ar num , Fl Fl before-context Ns = Ns Ar num
+.It Fl B Ar num , Fl Fl before-context= Ns Ar num
Print
.Ar num
lines of leading context before each match.
@@ -120,36 +123,58 @@ options.
.It Fl b , Fl Fl byte-offset
The offset in bytes of a matched pattern is
displayed in front of the respective matched line.
-.It Fl C Ns Op Ar num , Fl Fl context Ns = Ns Ar num
+.It Fl C Ns Oo Ar num Oc , Fl Fl context Ns Oo = Ns Ar num Oc
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 .
+The default value of
+.Ar num
+is
+.Dq 2
+and is equivalent to
+.Dq Fl A Ar 2 Fl B Ar 2 .
Note:
no whitespace may be given between the option and its argument.
.It Fl c , Fl Fl count
Only a count of selected lines is written to standard output.
-.It Fl Fl colour Ns = Ns Op Ar when , Fl Fl color Ns = Ns Op Ar when
-Mark up the matching text with the expression stored in
+.It Fl Fl colour= Ns Oo Ar when Oc , Fl Fl color= Ns Oo Ar when Oc
+Mark up the matching text with the expression stored in the
.Ev GREP_COLOR
environment variable.
-The possible values of when can be `never', `always' or `auto'.
-.It Fl D Ar action , Fl Fl devices Ns = Ns Ar action
-Specify the demanded action for devices, FIFOs and sockets.
-The default action is `read', which means, that they are read
-as if they were normal files.
-If the action is set to `skip', devices will be silently skipped.
-.It Fl d Ar action , Fl Fl directories Ns = Ns Ar action
-Specify the demanded action for directories.
-It is `read' by default, which means that the directories
+The possible values of
+.Ar when
+are
+.Dq Cm never ,
+.Dq Cm always
+and
+.Dq Cm auto .
+.It Fl D Ar action , Fl Fl devices= Ns Ar action
+Specify the demanded
+.Ar action
+for devices, FIFOs and sockets.
+The default
+.Ar action
+is
+.Dq Cm read ,
+which means, that they are read as if they were normal files.
+If the
+.Ar action
+is set to
+.Dq Cm skip ,
+devices are silently skipped.
+.It Fl d Ar action , Fl Fl directories= Ns Ar action
+Specify the demanded
+.Ar action
+for directories.
+It is
+.Dq Cm read
+by default, which means that the directories
are read in the same manner as normal files.
-Other possible values are `skip' to silently ignore the
-directories, and `recurse' to read them recursively, which
-has the same effect as the
+Other possible values are
+.Dq Cm skip
+to silently ignore the directories, and
+.Dq Cm recurse
+to read them recursively, which has the same effect as the
.Fl R
and
.Fl r
@@ -158,21 +183,27 @@ option.
Interpret
.Ar pattern
as an extended regular expression
-(i.e. force
+(i.e., force
.Nm grep
to behave as
.Nm egrep ) .
-.It Fl e Ar pattern , Fl Fl regexp Ns = Ns Ar pattern
-Specify a pattern used during the search of the input:
+.It Fl e Ar pattern , Fl Fl regexp= Ns Ar pattern
+Specify a
+.Ar 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
+or when a
+.Ar pattern
+begins with a dash
.Pq Sq - .
-.It Fl Fl exclude
+.It Fl Fl exclude Ar pattern
If specified, it excludes files matching the given
-filename pattern from the search.
+filename
+.Ar pattern
+from the search.
Note that
.Fl Fl exclude
and
@@ -185,11 +216,13 @@ pattern is specified, all files are searched that are
not excluded.
Patterns are matched to the full path specified,
not only to the filename component.
-.It Fl Fl exclude-dir
+.It Fl Fl exclude-dir Ar pattern
If
.Fl R
is specified, it excludes directories matching the
-given filename pattern from the search.
+given filename
+.Ar pattern
+from the search.
Note that
.Fl Fl exclude-dir
and
@@ -204,11 +237,11 @@ not excluded.
Interpret
.Ar pattern
as a set of fixed strings
-(i.e. force
+(i.e., force
.Nm grep
to behave as
.Nm fgrep ) .
-.It Fl f Ar file , Fl Fl file Ns = Ns Ar file
+.It Fl f Ar file , Fl Fl file= Ns Ar file
Read one or more newline separated patterns from
.Ar file .
Empty pattern lines match every input line.
@@ -220,7 +253,7 @@ is empty, nothing is matched.
Interpret
.Ar pattern
as a basic regular expression
-(i.e. force
+(i.e., force
.Nm grep
to behave as traditional
.Nm grep ) .
@@ -228,23 +261,24 @@ to behave as traditional
Always print filename headers with output lines.
.It Fl h , Fl Fl no-filename
Never print filename headers
-.Pq i.e. filenames
+.Pq i.e., filenames
with output lines.
.It Fl Fl help
Print a brief help message.
.It Fl I
Ignore binary files.
-This option is equivalent to
-.Fl Fl binary-file Ns = Ns Ar without-match
+This option is equivalent to the
+.Dq Fl Fl binary-file= Ns Cm without-match
option.
.It Fl i , Fl Fl ignore-case
Perform case insensitive matching.
By default,
.Nm grep
is case sensitive.
-.It Fl Fl include
-If specified, only files matching the
-given filename pattern are searched.
+.It Fl Fl include Ar pattern
+If specified, only files matching the given filename
+.Ar pattern
+are searched.
Note that
.Fl Fl include
and
@@ -253,11 +287,12 @@ patterns are processed in the order given.
If a name patches multiple patterns, the latest matching rule wins.
Patterns are matched to the full path specified,
not only to the filename component.
-.It Fl Fl include-dir
+.It Fl Fl include-dir Ar pattern
If
.Fl R
-is specified, only directories matching the
-given filename pattern are searched.
+is specified, only directories matching the given filename
+.Ar pattern
+are searched.
Note that
.Fl Fl include-dir
and
@@ -301,7 +336,7 @@ instead of
.Xr read 2
to read input, which can result in better performance under some
circumstances but can cause undefined behaviour.
-.It Fl m Ar num, Fl Fl max-count Ns = Ns Ar num
+.It Fl m Ar num , Fl Fl max-count= Ns Ar num
Stop reading the file after
.Ar num
matches.
@@ -325,7 +360,7 @@ If
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 o, Fl Fl only-matching
+.It Fl o , Fl Fl only-matching
Prints only the matching part of the lines.
.It Fl p
If
@@ -340,7 +375,7 @@ will only search a file until a match has been found,
making searches potentially less expensive.
.It Fl R , Fl r , Fl Fl recursive
Recursively search subdirectories listed.
-(i.e. force
+(i.e., force
.Nm grep
to behave as
.Nm rgrep ) .
@@ -352,7 +387,7 @@ The default is not to follow symbolic links.
.It Fl s , Fl Fl no-messages
Silent mode.
Nonexistent and unreadable files are ignored
-(i.e. their error messages are suppressed).
+(i.e., their error messages are suppressed).
.It Fl U , Fl Fl binary
Search binary files, but do not attempt to print them.
.It Fl u
@@ -380,23 +415,17 @@ Obsoleted.
.It Fl z , Fl Fl null-data
Treat input and output data as sequences of lines terminated by a
zero-byte instead of a newline.
-.It Fl Fl binary-files Ns = Ns Ar value
+.It Fl Fl binary-files= 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 :
-do not search binary files;
-and
-.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.
+Options are:
+.Bl -tag -compact -width "binary (default)"
+.It Cm binary No (default)
+Search binary files but do not print them.
+.It Cm without-match
+Do not search binary files.
+.It Cm text
+Treat all files as text.
+.El
.It Fl Fl line-buffered
Force output to be line buffered.
By default, output is line buffered when standard output is a terminal
@@ -405,7 +434,7 @@ and block buffered otherwise.
.Pp
If no file arguments are specified, the standard input is used.
Additionally,
-.Dq -
+.Dq Cm -
may be used in place of a file name, anywhere that a file name is accepted, to
read from standard input.
This includes both
@@ -425,12 +454,14 @@ No lines were selected.
An error occurred.
.El
.Sh EXAMPLES
+.Bl -dash
+.It
To find all occurrences of the word
.Sq patricia
in a file:
.Pp
.Dl $ grep 'patricia' myfile
-.Pp
+.It
To find all occurrences of the pattern
.Ql .Pp
at the beginning of a line:
@@ -448,14 +479,14 @@ and the
escapes the
.Ql \&. ,
which would otherwise match any character.
-.Pp
+.It
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
-.Pp
+.It
A simple example of an extended regular expression:
.Pp
.Dl $ egrep '19|20|25' calendar
@@ -463,10 +494,12 @@ A simple example of an extended regular expression:
Peruses the file
.Sq calendar
looking for either 19, 20, or 25.
+.El
.Sh SEE ALSO
.Xr ed 1 ,
.Xr ex 1 ,
.Xr sed 1 ,
+.Xr zgrep 1 ,
.Xr re_format 7
.Sh STANDARDS
The
Modified: head/usr.bin/grep/zgrep.1
==============================================================================
--- head/usr.bin/grep/zgrep.1 Mon Aug 20 22:16:15 2018 (r338121)
+++ head/usr.bin/grep/zgrep.1 Mon Aug 20 22:23:59 2018 (r338122)
@@ -24,7 +24,7 @@
.\"
.\" $FreeBSD$
.\"
-.Dd April 25, 2018
+.Dd August 21, 2018
.Dt ZGREP 1
.Os
.Sh NAME
@@ -43,9 +43,7 @@
.Nm zstdgrep ,
.Nm zstdegrep ,
.Nm zstdfgrep
-.Nd
-.Xr grep 1
-compressed files
+.Nd grep compressed files
.Sh SYNOPSIS
.Nm
.Oo Ar flags Oc Ar files
@@ -53,24 +51,28 @@ compressed files
.Oo Ar flags Oc Ar files
.Nm zfgrep
.Oo Ar flags Oc Ar files
+.Pp
.Nm bzgrep
.Oo Ar flags Oc Ar files
.Nm bzegrep
.Oo Ar flags Oc Ar files
.Nm bzfgrep
.Oo Ar flags Oc Ar files
+.Pp
.Nm lzgrep
.Oo Ar flags Oc Ar files
.Nm lzegrep
.Oo Ar flags Oc Ar files
.Nm lzfgrep
.Oo Ar flags Oc Ar files
+.Pp
.Nm xzgrep
.Oo Ar flags Oc Ar files
.Nm xzegrep
.Oo Ar flags Oc Ar files
.Nm xzfgrep
.Oo Ar flags Oc Ar files
+.Pp
.Nm zstdgrep
.Oo Ar flags Oc Ar files
.Nm zstdegrep
@@ -80,9 +82,11 @@ compressed files
.Sh DESCRIPTION
Allow
.Xr grep 1
-to read compressed files
+to read compressed files.
.Sh SEE ALSO
-.Xr grep 1
+.Xr bzip2 1 ,
+.Xr grep 1 ,
+.Xr xz 1
.Sh AUTHORS
This version of the
.Nm
More information about the svn-src-all
mailing list