Re: [patch #4610] Consolidated documentation patch

[Charles Levert]

* On Sunday 2005-11-13 at 23:21:31 +0100, Benno Schulenberg wrote:
> Charles Levert wrote:
> > +   * doc/grep.1, doc/grep.texi: Note that context lines are not
> > available
> > +     with --only-matching and that a warning is issued under such
> > uses.
> 
> Please don't add these unneeded explanations of obvious conflicts.

In this specific case, I made one point just
for this because I merged Julian's patch in,
and that patch was solely about that.


> > Places a line containing
> > .B \-\^\-
> > between contiguous groups of matches.
> 
> Hmm, it's maybe better to quote these double dashes (`--') instead 
> of putting them in bold, as on my konsole

I use that too!

> I see zero difference 
> between bold and normal dashes.

Ok for the quotes.


> Also quote the dash in "patterns beginning with -"; the info page 
> says "with a `-'".

Done.

For all long options with a hyphen-minus (U+002D)
character in the middle of their name, I used
\- there as well to make the troff output look
better (more like a minus than a hyphen).

I wish there was a way to get something that
looked more like a minus than a hyphen in troff,
but that still systematically output as a
hyphen-minus in nroff.  When using -Tlatin1
or -Tutf8, one often get a minus sign (U+2212)
from \- which prevents proper copy&paste from the
terminal screen, as programs don't recognize this
as the proper syntax for the option.  That is
what \- was designed to be (a real minus sign),
but it's not what man-page authors have gotten
in the habit of using it for.


> The `-z --null-data' option is missing from the man page.

Added.


> And to be fully consistent, the `options' at the top of that page 
> should probably be uppercased.

Done.


> > +Copyright @copyright{} 1999, 2000, 2001, 2002, 2005  Free
> > Software Foundation, Inc. 
> 
> The "2005" will only be true if this year a release is made, no?

If the content for the next release is completed
in 2005, yes.  Since this is yet unreleased,
there's also nobody yet to see it from a
copyright point-of-view, so it should not bother
their non-present "legal" self!  It will need to
be replaced by 2006 or 2007 if we only complete
a release by then.


> > +where there can be zero or more @var{options},
> 
> Maybe better start a new sentence: "There can...".

Ok.  Long sentences are more frequent in my
native language than in English.  Force of habit.
I now make three separate sentences for this.


> > address@hidden will only be seen as such
> > +(and not as an @var{input_file_name})
> > +if it wasn't already specified within @var{options},
> 
> It took a while before I understood that you were hinting at the -e 
> option.  As this is a "general synopsis", I don't think it is 
> necessary to mention this detail here.  Just saying that the general 
> form is "options pattern files, zero or more options, zero or more 
> files" will be enough, IMO.

I disagree.  Many man pages actually have two
distinct synopsis lines to make this clear.  So,

   ...
   (by using the @samp{-e@ @var{pattern}}
   or @samp{-f@ @var{file}} options).


> > address@hidden comes with a rich set of options
> > +from @sc{posix.2} and @sc{gnu} extensions.
> 
> This sentence has bothered me long enough now... Maybe better "a 
> rich set of options: several from @sc{posix.2}, and many @sc{gnu} 
> extensions.

Yes, me as well.

   @command{grep} comes with a rich set of options:
   some from @sc{posix.2} and some being @sc{gnu} extensions.

"rich", "several", and "many" is a little over
the board.


> > +Several additional options control
> > +which variant of the @command{grep} matching engine is used.
> > address@hidden Programs}.
> 
> This would be better placed after the menu, as otherwise the 
> "additional" doesn't make sense.  It also makes it stand out more.

Done.  The @node easily fits in one screen so
it can't be missed even by doing that.


> > address@hidden Generic Program Information
> 
> This subsection I'd really prefer to see near the end, just before 
> Other Options.

I knew you'd notice it.  I prefer having it at
the beginning because the whole documentation
thing (manual or --help) is about finding
what one is looking for.  Therefore, I think
mentioning --help is one of the first things
that should be done so that users have all the
tools they need to help themselves early on.
The @node/@subsection is a short one as well.