bug#31228: Update GREP manpage

[Ingo Schwarze]

Hi,

thanks for looking at this issue.

Paul Eggert wrote:
> Ingo Schwarze wrote:

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

> This does not work with Solaris nroff and troff, which we'd still
> like to port to, as Solaris is still a live platform.

That would require
 - creating man(7) versions from the master mdoc(7) versions
   on your build host with "mandoc -Tman" when building release
   tarballs and including these autogenerated man(7) versions
   into the tarballs in addition to the mdoc(7) versions
 - decide at autoconf time on the target system which version
   to install

Here is an example how sudo(8) does it:

  https://www.sudo.ws/repos/sudo/file/tip/configure.ac

But of course, i admit that it requires a bit of work, but it would
give your users better manual pages, in particular regarding the
HTML output, which you do seem to care about considering the
view you express on option 2:

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

> Although this would port, it would be less readable on newer systems.
> For example, the HTML man page wouldn't contain links to the grep
> manual. We can do better.

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

> (3) is not as unportable as Ingo suggested, since the MT and UR macros
> can work outside the GNU environment when included in the man page.
> Please try the attached patch, which I've installed into the grep
> master. If it runs afoul of the troff subset that Ingo is using, please
> let us know and (ideally) suggest a fix.

I'm not a big fan of copying macro implementations into individual
manual pages.  It bloats the page, and there is always a risk that
the fallback implementation, or the conditionals needed to enable
or disable it,  may run afoul of some formatter out there, in
particular when you use fancy stuff like .do, .ftr, .ev, .di,
.chop...

That said, groff and mandoc output of what you committed to git are
byte-by-byte identical except for the following one-blank difference
(mandoc output looks minimally better than groff output at that
point, groff prints one excess blank character because it wrongly
detects the end of a sentence where there is none):

 $ gmdiff grep.in.1
 ========== grep.in.1 ========== 
roff errors:
mandoc errors:
mandoc: grep.in.1:41:9: UNSUPP: unsupported roff request: do
mandoc: grep.in.1:42:1: UNSUPP: unsupported roff request: do
mandoc: grep.in.1:43:1: UNSUPP: unsupported roff request: do
--- /tmp/roff.out       Sat Apr 21 00:08:05 2018
+++ /tmp/mandoc.out     Sat Apr 21 00:08:05 2018
@@ -263,8 +263,8 @@
               the whole name, or any suffix starting after a // and before a
               +non-//.  When searching recursively, skip any subfile whose 
base
               name matches _G_L_O_B; the base name is the part after the 
last //.
-              A pattern can use **, ??, and [[...]]  as wildcards, and \\ 
to quote
-              a wildcard or backslash character literally.
+              A pattern can use **, ??, and [[...]] as wildcards, and \\ 
to quote a
+              wildcard or backslash character literally.
 
        ----eexxcclluuddee--ffrroomm==_F_I_L_E
               Skip files whose base name matches any of the file-name globs

Your commit also happens to work with Heirloom roff.

So it *does* seem to be an improvement.

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

> No, Solaris nroff can format the grep man page properly and it does not
> define \n(.g.

I don't doubt that an archaic formatter like Solaris 11 nroff can
format a page specifically written to work with archaic software,
even if \(.g is used.  :-)

What i meant is from the perspective of the formatter:  If a formatter
intends to work well with most manual pages found in the wild,
nowadays, it *must* define \(.g, even if it is not groff.  For
example, mandoc handles over 99% of the software packages in our
ports tree that contain manual pages.  Without defining \(.g, it
couldn't even come close.  I have no idea how many current manual
pages Solaris 11 nroff may be able to handle - i guess it may fail
on quite a few.

Anyway, thank you for fixing this!
  Ingo