Re: Changes to grep/doc/grep.1

[Charles Levert]

* On Thursday 2005-11-10 at 23:03:28 +0000, Julian Foad wrote:
> Benno Schulenberg wrote:
> >
> >The second patch adds the "(using wildcard matching)" also to the 
> >explanation of `--include'.  It removes the "and directories", to 
> >make the text describe the actual behaviour of grep.
> 
> I'm just preparing a more comprehensive set of documentation tweaks that 
> includes adding "(using wildcard matching)", and also says what that means, 
> so wait and have a look at what I post in the next day or two.

I have started working on something too.
I'll post what I have later today, so that
we can explore merging opportunities as soon
as possible to avoid duplication of efforts.


> As for "and directories", that's always been controversial; are you sure 
> that change matches what the current source does?

I verified the current actual behavior; yes.


> Is that what we want it to do?

That's another matter.
Let's first document what it does now.


> I'll have a look into it later.

In my copy, I have changed this to

   Search only files with base names that match @var{file_pattern}
   (using wildcard matching).

The problem is that, with so much matching
being involved with grep, it's worth noting
here that this pertains to the file names,
not the files' content.
It's also the base names, not the full paths.


> >The third patch applies after the first two; it reorders the GNU 
> >options alphabetically.
> 
> I haven't reviewed that yet.  Just to give a hint as to why it may not be 
> uncontroversial: It's possible that we may prefer to have some deviations 
> from strict alphabetical order in order to keep some related options 
> together.

In my copy, I now have

   @chapter Invoking @command{grep}
      @section @sc{posix} Options
      @section @sc{gnu} Extensions
         @subsection Generic Program Information
         @subsection Context Line Control
         @subsection Output Line Prefix Control
         @subsection File and Directory Selection
         @subsection Other Options

with lexicographical order inside it, leaving

   @chapter @command{grep} programs

where it is but referencing it from the beginning
of the former chapter, not the end.

That's only for the TeXinfo documentation, though.
I find the man page being ok in this regard,
given what it is and tradition regarding having
few subsections there (i.e., a shallow hierarchy).

One problem is whether to order options by their
long names or by their short ones.
A few, such as -a/--text, are problematic.
By grouping them in smaller subsections, the
effect of this problem is strongly alleviated.
Remember, there are indexes in the TeXinfo doc.