Subject: Re: bug#74502: grep.in.1: Some remarks about this man page

From: Paul Eggert <[email-masked]>
Date: Fri, 21 Mar 2025 13:25:34 -0700

On 11/23/24 18:17, Paul Eggert wrote:
> that's a recently-introduced groff bug. I reported it here:
> 
> https://savannah.gnu.org/bugs/index.php?66481

 From the followup to that groff bug report, it appears that the groff 
maintainers don't consider this to be a bug, though they do say it is a 
compatibility issue. To work around this for grep, I installed the first 
attached patch. I noticed some other glitches too (some with traditional 
troff) and installed the second attached patch while I was in the 
neighborhood.

Closing the bug report. Thanks again for reporting the issue.

From 9863d53a5fc9277beb3dbc97e434d396b34c2a6e Mon Sep 17 00:00:00 2001
From: Paul Eggert <[email-masked]>
Date: Fri, 21 Mar 2025 10:01:06 -0700
Subject: [PATCH 1/2] doc: use \w@...@ not \w|...|

* doc/grep.in.1: Avoid warnings in bleeding-edge groff.
---
 doc/grep.in.1 | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/grep.in.1 b/doc/grep.in.1
index 789cf5a..d0f757d 100644
--- a/doc/grep.in.1
+++ b/doc/grep.in.1
@@ -11,7 +11,7 @@
 .
 .TH GREP 1 \*(Dt "GNU grep @VERSION@" "User Commands"
 .
-.if !\w|\*(lq| \{\
+.if !\w@\*(lq@ \{\
 .\" groff an-old.tmac does not seem to be in use, so define lq and rq.
 .	ie \n(.g \{\
 .		ds lq \(lq\"
@@ -24,7 +24,7 @@
 .\}
 .
 .as la
-.if !\w|\*(la| \{\
+.if !\w@\*(la@ \{\
 .\" groff an-ext.tmac does not seem to be in use, so define the parts of
 .\" it that are used below.  For a copy of groff an-ext.tmac, please see:
 .\" https://git.savannah.gnu.org/cgit/groff.git/plain/tmac/an-ext.tmac
-- 
2.49.0

From 920daa57a4129b1b7b7c2387b01401c8981bee76 Mon Sep 17 00:00:00 2001
From: Paul Eggert <[email-masked]>
Date: Fri, 21 Mar 2025 10:16:50 -0700
Subject: [PATCH 2/2] doc: update man for groff 1.23.0 and apostrophes

* doc/grep.in.1: Merge from groff 1.23.0 tmac/an-ext.tmac.
On Groff, fix usage neutral apostrophes;
they cannot be reliably fixed in traditional troff.
---
 doc/grep.in.1 | 172 +++++++++++++++++++++++++-------------------------
 1 file changed, 85 insertions(+), 87 deletions(-)

diff --git a/doc/grep.in.1 b/doc/grep.in.1
index d0f757d..1150b5d 100644
--- a/doc/grep.in.1
+++ b/doc/grep.in.1
@@ -2,7 +2,7 @@
 .de dT
 .ds Dt \\$2
 ..
-.dT Time-stamp: "2019-12-29"
+.dT Time-stamp: "2025-03-21"
 .\" Update the above date whenever a change to either this file or
 .\" grep.c's 'usage' function results in a nontrivial change to the man page.
 .\" In Emacs, you can update the date by running 'M-x time-stamp'
@@ -11,8 +11,11 @@
 .
 .TH GREP 1 \*(Dt "GNU grep @VERSION@" "User Commands"
 .
+.ie \n(.g .ds ' \(aq
+.el .ds ' '
 .if !\w@\*(lq@ \{\
-.\" groff an-old.tmac does not seem to be in use, so define lq and rq.
+.\" Recent-enough groff an.tmac does not seem to be in use,
+.\" so define the strings lq and rq.
 .	ie \n(.g \{\
 .		ds lq \(lq\"
 .		ds rq \(rq\"
@@ -23,115 +26,110 @@
 .	\}
 .\}
 .
-.as la
-.if !\w@\*(la@ \{\
+.as mC
+.if !\w@\*(mC@ \{\
 .\" groff an-ext.tmac does not seem to be in use, so define the parts of
-.\" it that are used below.  For a copy of groff an-ext.tmac, please see:
-.\" https://git.savannah.gnu.org/cgit/groff.git/plain/tmac/an-ext.tmac
-.\" --- Start of lines taken from groff an-ext.tmac
+.\" it that are used below, taken from groff 1.23.0.  For a copy, please see:
+.\" https://git.savannah.gnu.org/cgit/groff.git/plain/tmac/an-ext.tmac?id=1.23.0
+.nr mG \n(.g-1
+.\" --- Start of lines taken from groff an-ext.tmac,
+.\" except with "nr mH 14" replaced by "nr mH 0"
+.\" and with mS, SY, YS definitions omitted.
 .
-.\" Check whether we are using grohtml.
-.nr mH 0
-.if \n(.g \
-.  if '\*(.T'html' \
-.    nr mH 1
+.\" Define this to your implementation's constant-width typeface.
+.ds mC CW
+.if n .ds mC R
 .
+.\" Save the automatic hyphenation mode.
+.\"
+.\" In AT&T troff, there was no register exposing the hyphenation mode,
+.\" and no way to save and restore it.  Set `mH` to a reasonable value
+.\" for your implementation and preference.
+.de mY
+.  ie !\\n(.g \
+.    nr mH 0
+.  el \
+.    do nr mH \\n[.hy] \" groff extension register
+..
 .
-.\" Map mono-width fonts to standard fonts for groff's TTY device.
-.if n \{\
-.  do ftr CR R
-.  do ftr CI I
-.  do ftr CB B
-.\}
+.nr mE 0 \" in an example (EX/EE)?
+.
+.\" Prepare link text for mail/web hyperlinks.  `MT` and `UR` call this.
+.de mV
+.  ds m1 \\$1\"
+..
+.
+.
+.\" Emit hyperlink.  The optional argument supplies trailing punctuation
+.\" after link text.  `ME` and `UE` call this.
+.de mQ
+.  mY
+.  nh
+<\\*(m1>\\$1
+.  hy \\n(mH
+..
 .
-.\" groff has glyph entities for angle brackets.
-.ie \n(.g \{\
-.  ds la \(la\"
-.  ds ra \(ra\"
-.\}
-.el \{\
-.  ds la <\"
-.  ds ra >\"
-.  \" groff's man macros control hyphenation with this register.
-.  nr HY 1
-.\}
 .
 .\" Start URL.
+.if \n(.g-\n(mG \{\
 .de UR
-.  ds m1 \\$1\"
-.  nh
-.  if \\n(mH \{\
-.    \" Start diversion in a new environment.
-.    do ev URL-div
-.    do di URL-div
-.  \}
+.  mV \\$1
 ..
+.\}
 .
 .
 .\" End URL.
+.if \n(.g-\n(mG \{\
 .de UE
-.  ie \\n(mH \{\
-.    br
-.    di
-.    ev
-.
-.    \" Has there been one or more input lines for the link text?
-.    ie \\n(dn \{\
-.      do HTML-NS "<a href=""\\*(m1"">"
-.      \" Yes, strip off final newline of diversion and emit it.
-.      do chop URL-div
-.      do URL-div
-\c
-.      do HTML-NS </a>
-.    \}
-.    el \
-.      do HTML-NS "<a href=""\\*(m1"">\\*(m1</a>"
-\&\\$*\"
-.  \}
-.  el \
-\\*(la\\*(m1\\*(ra\\$*\"
-.
-.  hy \\n(HY
+.  mQ \\$1
 ..
+.\}
 .
 .
 .\" Start email address.
+.if \n(.g-\n(mG \{\
 .de MT
-.  ds m1 \\$1\"
-.  nh
-.  if \\n(mH \{\
-.    \" Start diversion in a new environment.
-.    do ev URL-div
-.    do di URL-div
-.  \}
+.  mV \\$1
 ..
+.\}
 .
 .
 .\" End email address.
+.if \n(.g-\n(mG \{\
 .de ME
-.  ie \\n(mH \{\
-.    br
-.    di
-.    ev
+.  mQ \\$1
+..
+.\}
+.
 .
-.    \" Has there been one or more input lines for the link text?
-.    ie \\n(dn \{\
-.      do HTML-NS "<a href=""mailto:\\*(m1"">"
-.      \" Yes, strip off final newline of diversion and emit it.
-.      do chop URL-div
-.      do URL-div
-\c
-.      do HTML-NS </a>
-.    \}
-.    el \
-.      do HTML-NS "<a href=""mailto:\\*(m1"">\\*(m1</a>"
-\&\\$*\"
+.\" Start example.
+.if \n(.g-\n(mG \{\
+.de EX
+.  br
+.  if !\\n(mE \{\
+.    nr mF \\n(.f
+.    nr mP \\n(PD
+.    nr PD 1v
+.    nf
+.    ft \\*(mC
+.    nr mE 1
 .  \}
-.  el \
-\\*(la\\*(m1\\*(ra\\$*\"
+..
+.\}
+.
 .
-.  hy \\n(HY
+.\" End example.
+.if \n(.g-\n(mG \{\
+.de EE
+.  br
+.  if \\n(mE \{\
+.    ft \\n(mF
+.    nr PD \\n(mP
+.    fi
+.    nr mE 0
+.  \}
 ..
+.\}
 .\" --- End of lines taken from groff an-ext.tmac
 .\}
 .
@@ -408,7 +406,7 @@ Display input actually coming from standard input as input coming from file
 This can be useful for commands that transform a file's contents
 before searching,
 e.g.,
-.BR "gzip \-cd foo.gz | grep \-\^\-label=foo \-H 'some pattern'" .
+.BR "gzip \-cd foo.gz | grep \-\^\-label=foo \-H \*'some pattern\*'" .
 See also the
 .B \-H
 option.
@@ -599,7 +597,7 @@ On the other hand, when reading files whose text encodings are
 unknown, it can be helpful to use
 .B \-a
 or to set
-.B LC_ALL='C'
+.B LC_ALL=\*'C\*'
 in the environment, in order to find more matches even if the matches
 are unsafe for direct display.
 .TP
@@ -1313,7 +1311,7 @@ even if only one file name happens to be of the form \*(lq*g*.h\*(rq.
 .PP
 .in +2n
 .EX
-$ \fBgrep\fP \-n \-\^\- 'f.*\e.c$' *g*.h /dev/null
+$ \fBgrep\fP \-n \-\^\- \*'f.*\e.c$\*' *g*.h /dev/null
 argmatch.h:1:/* definitions and prototypes for argmatch.c
 .EE
 .in
-- 
2.49.0