bug#45353: Errors in man pages

[Jim Meyering]

On Mon, Dec 21, 2020 at 8:12 AM Helge Kreutzmann <debian@helgefjell.de> wrote:
...

Thank you for the suggestions.

> Man page: grep.1
> Issue: The option was mentioned above!
>
> "Suppress normal output; instead print a count of matching lines for each "
> "input file.  With the B<-v>, B<-\\^-invert-match> option (see below), count "
> "non-matching lines."

That is expected. Its primary description is above.
This part tells how it works when combined with the -c option.

> --
> Man page: grep.1
> Issue: Reorder text?
>
> "Report Unix-style byte offsets.  This switch causes B<grep> to report byte "
> "offsets as if the file were a Unix-style text file, i.e., with CR characters 
> "
> "stripped off.  This will produce results identical to running B<grep> on a "
> "Unix machine.  This option has no effect unless B<-b> option is also used; "
> "it has no effect on platforms other than MS-DOS and MS-Windows."

As mentioned below, this entire option (-u) is about to disappear.

> --
> Man page: grep.1
> Issue 1: pcresyntax(3) → B<pcresyntax>(3)
> Issue 2: pcrepattern(3) → B<pcrepattern>(3)
>
> "B<grep> understands three different versions of regular expression syntax: "
> "``basic'' (BRE), ``extended'' (ERE) and ``perl'' (PCRE).  In GNU B<grep> "
> "there is no difference in available functionality between basic and extended 
> "
> "syntaxes.  In other implementations, basic regular expressions are less "
> "powerful.  The following description applies to extended regular "
> "expressions; differences for basic regular expressions are summarized "
> "afterwards.  Perl-compatible regular expressions give additional "
> "functionality, and are documented in pcresyntax(3) and pcrepattern(3), but "
> "work only if PCRE is available in the system."

Done.

> --
> Man page: grep.1
> Issue: Order of entrie not according to man-pages(7)
>
> "B<awk>(1), B<cmp>(1), B<diff>(1), B<find>(1), B<perl>(1), B<sed>(1), "
> "B<sort>(1), B<xargs>(1), B<read>(2), B<pcre>(3), B<pcresyntax>(3), "
> "B<pcrepattern>(3), B<terminfo>(5), B<glob>(7), B<regex>(7)."

I read man-pages(7)'s section on SEE ALSO and found only one nit here.
It terminated the list with a period, while man-pages(7) says to
provide no period.

> The list should be ordered by section number and then alphabetically by name. 
>  Do not terminate this list with a period.

If there's something else, please be more precise.

Actually, for each suggestion in the future, please provide an actual
diff. That would be far better.

> --
> Man page: grep.1
> Issue: PATTERNS → I<PATTERNS>
>
> "Interpret PATTERNS as Perl-compatible regular expressions (PCREs).  This "
> "option is experimental when combined with the B<-z> (B<-\\^-null-data>)  "
> "option, and B<grep -P> may warn of unimplemented features."
> --
> Man page: grep.1
> Issue: Not in "grep --help"; remove?
>
> "B<-y>"

This is deliberate. Undocumenting is a necessary step prior to removal
of legacy options like this:

  $ git grep -e -y doc|tail -1
  doc/grep.texi:@option{-y} is an obsolete synonym that is provided
for compatibility.

> --
> Man page: grep.1
> Issue: Not in --help; is it a valid option?
>
> "B<-u>, B<-\\^-unix-byte-offsets>"

Similarly,
      case 'u':
        /* Obsolete option; it has no effect.  FIXME: Diagnose use of
           this option starting in (say) the year 2020.  */
        break;

I'm doing as that suggests in a separate commit.

> --
> Man page: grep.1
> Issue: grep should be in B<>
>
> "Read all files under each directory, recursively, following symbolic links "
> "only if they are on the command line.  Note that if no file operand is "
> "given, grep searches the working directory.  This is equivalent to the B<-d "
> "recurse> option."

Done.

I wrote the attached patch in your name.
Let me know if there's anything else to be done here.

0001-doc-adjust-man-page-syntax.patch
Description: Binary data