bug#31228: Update GREP manpage

[Laura Morales]

Hi, I was trying to convert grep.1 to HTML and I discovered that there are some 
issues... in particular it seems to be using an unsupported macro for email 
addresses and URLs. You can see an example here 
https://manpages.debian.org/stretch/grep/grep.1.en.html#Reporting_Bugs the 
output is

Email bug reports to An and a are available.

but instead it should be

Email bug reports to the bug-reporting address <address@hidden>. An email 
archive <http://lists.gnu.org/mailman/listinfo/bug-grep> and a bug tracker 
<http://debbugs.gnu.org/cgi/pkgreport.cgi?package=grep> are available.

I've asked Ingo who is the maintainer of mandoc, and the answer seems to be 
that the grep manpage is malformed and should be updated.
Can you guys please fix the grep manpage? Thank you in advance.

Following is Ingo's reply:
--------------------------

> Look at this page: https://paste.debian.net/plain/1021106
> If I do (from Linux):
> $ mandoc -Thtml grep.1 > grep.1.html
> mandoc is not producing the output for email addresses and URLs.
> For instance take a look at the BUGS section
>
> .SH BUGS
> .SS "Reporting Bugs"
> Email bug reports to
> .MTO address@hidden "the bug-reporting address" .
> An
> .URL http://lists.gnu.org/mailman/listinfo/bug-grep "email archive"
> and a
> .URL http://debbugs.gnu.org/cgi/pkgreport.cgi?package=grep "bug tracker"
> are available.
>
> the HTML output is
>
> BUGS
> Reporting Bugs
> Email bug reports to An and a are available.
>
> Looks like it's completely skipping some macros.
> Is this a bug

Not a bug, no.

> or is there some flag that I can turn on to enable all macros?

No. We do not believe in options, stuff is supposed to just
work without users twiddling knobs.


This is supposed to be a groff_man(7) document but .MTO and .URL
are not man macros.

The man language does *not* provide markup for mail addresses
or URIs.

Please tell the maintainers of GNU grep(1) to fix their manual
page. They have the following four options. The smaller the
number, the better, cleaner, and more portable:

1. BEST:
Switch to the better mdoc(7) language which does provide
such markup.

2. If they insist on using the obselete man(7) language and
want to remain portable, use standard macros like .I and
.B and accept that no hyperlinks will appear. It is
a limitation of the chosen language. You can't have the
cake and eat it, too.

3. If they don't care about portability and live in a GNU-only
world, use the -man-ext macros .MT and .UR, documented in
groff_man(7). mandoc(1) implements these for GNU compatibility,
but other formatters may not.

4. WORST:
If they absolutely insist on using the alien www.tmac macros
(even though it is irresponsible to mix random alien macro sets
into manual page markup), then at least fix the feature test
as follows:

.mso www.tmac
.if !dMTO \{\
. de MTO
\\$2 \(la\\$1\(ra\\$3
..
.\}
.if !dURL \{\
. de URL
\\$2 \(la\\$1\(ra\\$3
..
.\}

or maybe even better simply

. de MTO
\\$2 \(la\\$1\(ra\\$3
..
. de URL
\\$2 \(la\\$1\(ra\\$3
..
.mso www.tmac

because defining the macros first and then overriding them with GNU
implementations when available avoids the potentially non-portable
and fragile conditional.

But note that i do not recommend option 4 at all. It works with
groff and mandoc, but it is exceeding ugly and potentially non-
portable. Manual pages have no business whatsoever defining their
own macros!

Also note that using \(.g to test for availability of features is
utterly stupid. *ANY* formatter that wants to stand a chance to
format anything properly positively *must* define it, no matter
whether it is groff or not.

Feel free to include this message, or extracts from it as you see
fit, when reporting to the GNU grep(1) maintainers.

Yours,
Ingo