Date: Mon, 20 Aug 2018 22:23:59 +0000 (UTC) From: Mateusz Piotrowski <0mp@FreeBSD.org> To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r338122 - head/usr.bin/grep Message-ID: <201808202223.w7KMNxOG068922@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201808202223.w7KMNxOG068922>