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

[Stepan Kasal]

Hi Julian,

On Wed, Dec 01, 2004 at 06:45:32PM +0000, Julian Foad wrote:
> It would be nice to use a consistent quoting style.

Fixed.

> >-  - 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.

:-)

> >+.BI \-\^\-exclude= FILE_PATTERN
> >+.RI "Skip files " "and directories" " that match " FILE_PATTERN.
> 
> Could you explain to me what this use of separately quoted substrings means?

These are nroff macros.  On the first line, the first parameter is ptinted in
Bold, the second in italics, third would be bold, fourth in italics, ... etc.
The second line is similar: first parameters in in regular font, second in
italics, third regular, ...

All these parameters are concatenated; that means that on the first line,
you won't see any space between --exclude= and FILE_PATTERN.
The second line needs quotes to preserve the spaces so we get something
similar to:
> >+Skip files @emph{and directories} matching @var{file_pattern}.

> 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?

Bug #11017 is a reminder for me.  A long explanation is attached to patch
#3521.  In short, I want that

        grep -r pat --include='*.c'
and
        grep -r pat --exclude='.svn'

both work as the user would expected.

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

In this case, I want to have the documentation ahead.  The code will be
changed as part of the rewrite of the main loop; I'm afraid we could forget
to fix the documentation then.

> >+      --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.

Fixed; this also makes space to change ``pattern'' to ``file pattern''.

> "occures" -> "occurs".

Fixed.

> Why change this to the passive voice?

I have no opinion, I just inherited this from Benno's patch.
Feel free to rephrase it, you have the authority of being native speaker.

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

I don't think we have to address this explicitely.

The logic should be like this:
1) Exits with status 0 if a line is selected, with status 1 otherwise.
2) As an exception to the above rule, if a trouble occurs and -q was not
specified, grep exits with status 2.

Thusly, if -q was given, the first rule is used, no matter whether an error
occurs.

Updated patch is attached.

Regards,
        Stepan

grep-file-pattern4.patch
Description: Text document