Re: [patch #4610] Consolidated documentation patch

[Benno Schulenberg]

Charles Levert wrote:
> * 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.

Yes, sorry -- that's not what I meant.  I meant the application of 
the patch: making the man and info pages mention that a certain 
combination of options gives out a warning.  Such a mention is 
really not needed, IMHO.  But as you've meanwhile concluded that 
the warning itself is bogus, I guess it will disappear?

> When using -Tlatin1
> or -Tutf8, one often get a minus sign (U+2212)
> from \- which prevents proper copy&paste from the
> terminal screen,

Hmm, strange things you do.  :)  Copy-pasting options off of man 
pages...

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

Okay, but then it could maybe be phrased a bit shorter:

     @var{pattern} is only present
     if not already specified within the @var{options}
     (by using @samp{-e@ @var{pattern}}
     or @samp{-f@ @var{file}}).

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

But my thinking is: if users know to find the info page, they surely 
know about --help and --version and it's pointless or even annoying 
to mention these first.  But okay, it's not worth arguing about.

Benno