Re: [bug-grep] doc bug in grep; PATTERN implies a regexp used in --include or --exclude

[Julian Foad]

Stepan Kasal wrote:
> Updated patch attached.


> Index: ChangeLog
> ===================================================================
> RCS file: /cvsroot/grep/grep/ChangeLog,v
> retrieving revision 1.207
> diff -u -r1.207 ChangeLog
> --- ChangeLog   23 Nov 2004 12:49:36 -0000      1.207
> +++ ChangeLog   1 Dec 2004 14:09:50 -0000
> @@ -1,3 +1,16 @@
> +2004-12-01  Stepan Kasal  <address@hidden>
> +
> +       * src/grep.c (usage): Use ``FILE_PATTERN'' for --include and --exclude,
> +         change "only print" to "print only".

It would be nice to use a consistent quoting style.

> +       * doc/grep.1: Likewise; state that wildcard matching is used.
> +       * dfa.c, NEWS: Fix typos.
> +
> +2004-11-28  Benno Schulenberg  <address@hidden>  (tiny change)
> +
> +       * src/grep.c (usage): Clean up several details in the usage string.
> +       * doc/grep.1: Fix descriptions of --include and --exclude.
> +       * doc/grep.texi: Likewise.
> +

> Index: NEWS
> ===================================================================
> RCS file: /cvsroot/grep/grep/NEWS,v
> retrieving revision 1.38
> diff -u -r1.38 NEWS
> --- NEWS        26 Mar 2002 15:37:07 -0000      1.38
> +++ NEWS        1 Dec 2004 14:09:50 -0000
> @@ -28,7 +28,7 @@
>      grep -e '\(a\)\1' -e '\(b\)\1'
>      The last backref \1 in the second expression refer to \(b\)
>  
> -  - The new option --include=PATTERN will only search matching files
> +  - The new option --include=PATTERN will search only matching files

There is not much point in editing old news, but you can if you want to.

> Index: doc/grep.1
> ===================================================================
> RCS file: /cvsroot/grep/grep/doc/grep.1,v
> retrieving revision 1.25
> diff -u -r1.25 grep.1
> --- doc/grep.1  19 Nov 2004 13:51:29 -0000      1.25
> +++ doc/grep.1  1 Dec 2004 14:09:50 -0000
> @@ -186,6 +186,9 @@
>  as the pattern; useful to protect patterns beginning with
>  .BR \- .
>  .TP
> +.BI \-\^\-exclude= FILE_PATTERN
> +.RI "Skip files " "and directories" " that match " FILE_PATTERN.
> +.TP

Could you explain to me what this use of separately quoted substrings means?

>  .BR \-F ", " \-\^\-fixed-strings
>  Interpret
>  .I PATTERN
> @@ -228,6 +231,11 @@
>  .I PATTERN
>  and the input files.
>  .TP
> +.BI \-\^\-include= FILE_PATTERN
> +Search only files that match
> +.I FILE_PATTERN
> +(using wildcard matching).
> +.TP

No mention of directories here?  Bug #11017 doesn't explain why we would want 
"--exclude" to exclude specified directories but would not want "--include" to 
exclude non-specified directories.  Also, why would we want to change the 
documentation of that behaviour separately from the patch that changes the 
behaviour?  What if we decide that that bug report is not going to be fixed in 
that way?

I think this patch should document the current behaviour.  If we change the 
behaviour then we should change the documentation at the same time.


> Index: doc/grep.texi
> ===================================================================
> RCS file: /cvsroot/grep/grep/doc/grep.texi,v
> retrieving revision 1.47
> diff -u -r1.47 grep.texi
> --- doc/grep.texi       19 Nov 2004 13:51:29 -0000      1.47
> +++ doc/grep.texi       1 Dec 2004 14:09:51 -0000
> @@ -416,14 +416,13 @@
>  @opindex --include
>  @cindex include files
>  @cindex searching directory trees
> -When processing directories recursively, only files matching @var{file_pattern}
> -will be search.
> +Search only files matching @var{file_pattern}.
>  
>  @item address@hidden
>  @opindex --exclude
>  @cindex exclude files
>  @cindex searching directory trees
> -When processing directories recursively, skip files matching 
> @var{file_pattern}.
> +Skip files @emph{and directories} matching @var{file_pattern}.

So it looks like this really is what you mean ... OK.


> Index: src/grep.c
> ===================================================================
> RCS file: /cvsroot/grep/grep/src/grep.c,v
> retrieving revision 1.86
> diff -u -r1.86 grep.c
> --- src/grep.c  23 Nov 2004 10:00:48 -0000      1.86
> +++ src/grep.c  1 Dec 2004 14:09:51 -0000
> @@ -1123,21 +1123,21 @@
>        --label=LABEL         print LABEL as filename for standard input\n\
>    -o, --only-matching       show only the part of a line matching PATTERN\n\
>    -q, --quiet, --silent     suppress all normal output\n\
> -      --binary-files=TYPE   assume that binary files are TYPE\n\
> -                            TYPE is 'binary', 'text', or 'without-match'\n\
> +      --binary-files=TYPE   assume that binary files are TYPE;\n\
> +                            TYPE is `binary', `text', or `without-match'\n\
>    -a, --text                equivalent to --binary-files=text\n\
>    -I                        equivalent to --binary-files=without-match\n\
> -  -d, --directories=ACTION  how to handle directories\n\
> -                            ACTION is 'read', 'recurse', or 'skip'\n\
> -  -D, --devices=ACTION      how to handle devices, FIFOs and sockets\n\
> -                            ACTION is 'read' or 'skip'\n\
> +  -d, --directories=ACTION  how to handle directories;\n\
> +                            ACTION is `read', `recurse', or `skip'\n\
> +  -D, --devices=ACTION      how to handle devices, FIFOs and sockets;\n\
> +                            ACTION is `read' or `skip'\n\
>    -R, -r, --recursive       equivalent to --directories=recurse\n\
> -      --include=PATTERN     files that match PATTERN will be examined\n\
> -      --exclude=PATTERN     files that match PATTERN will be skipped.\n\
> -      --exclude-from=FILE   files that match PATTERN in FILE will be 
> skipped.\n\
> -  -L, --files-without-match only print FILE names containing no match\n\
> -  -l, --files-with-matches  only print FILE names containing matches\n\
> -  -c, --count               only print a count of matching lines per FILE\n\
> +      --include=FILE_PATTERN  search only files that match FILE_PATTERN\n\
> +      --exclude=FILE_PATTERN  skip files and directories matching 
> FILE_PATTERN\n\
> +      --exclude-from=FILE   files matching any pattern from FILE are skipped\n\

This line is still in the passive voice while everything else is now in the 
active voice.

> +  -L, --files-without-match print only names of FILEs containing no match\n\
> +  -l, --files-with-matches  print only names of FILEs containing matches\n\
> +  -c, --count               print only a count of matching lines per FILE\n\
>    -Z, --null                print 0 byte after FILE name\n"));

>  `egrep' means `grep -E'.  `fgrep' means `grep -F'.\n\
> -With no FILE, or when FILE is -, read standard input.  If less than\n\
> -two FILEs given, assume -h.  Exit status is 0 if match, 1 if no match,\n\
> -and 2 if trouble.\n"));
> +With no FILE, or when FILE is -, standard input is read.  If less than two\n\
> +FILEs are given, -h is assumed.  Exit status is 0 if any line was selected,\n\
> +1 otherwise; if any error occures and -q was not given, the exit status is 
> 2.\n"));

"occures" -> "occurs".

Why change this to the passive voice?

Do we need to say what the status is if an error occurs and "-q" was given?