On 04/20/2018 09:03 AM, Laura Morales quoted Ingo Schwarze as writing:
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.
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.
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.
>From fb9649338de86dc73bd5415b68d3ceeb99884905 Mon Sep 17 00:00:00 2001
From: Paul Eggert <egg...@cs.ucla.edu>
Date: Fri, 20 Apr 2018 12:44:48 -0700
Subject: [PATCH] doc: port better to mandoc
* doc/grep.in.1: Check for groff and its macro packages
independently, as groff can be used with non-groff macro packages.
Use an-ext style macros rather than www.tmac style, as this should
be more portable to mandoc. Problem reported by Laura Morales and
Ingo Schwarze (Bug#31228).
---
doc/grep.in.1 | 143 +++++++++++++++++++++++++++++++++++++++++++++++++++-------
1 file changed, 127 insertions(+), 16 deletions(-)
diff --git a/doc/grep.in.1 b/doc/grep.in.1
index ecc8105..9393b37 100644
--- a/doc/grep.in.1
+++ b/doc/grep.in.1
@@ -9,28 +9,131 @@
.\" after you make a change that you decide is nontrivial.
.\" It is no big deal to forget to update the date.
.
-.if !\n(.g \{\
-. if !\w|\*(lq| \{\
-. ds lq ``
-. if \w'\(lq' .ds lq "\(lq
+.TH GREP 1 \*(Dt "GNU grep @VERSION@" "User Commands"
+.
+.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\"
+. ds rq \(rq\"
. \}
-. if !\w|\*(rq| \{\
+. el \{\
+. ds lq ``
. ds rq ''
-. if \w'\(rq' .ds rq "\(rq
. \}
.\}
.
-.ie \n[.g] .mso www.tmac
+.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
+.\" --- Start of lines taken from groff an-ext.tmac
+.
+.\" Check whether we are using grohtml.
+.nr mH 0
+.if \n(.g \
+. if '\*(.T'html' \
+. nr mH 1
+.
+.
+.\" 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
+.\}
+.
+.\" groff has glyph entities for angle brackets.
+.ie \n(.g \{\
+. ds la \(la\"
+. ds ra \(ra\"
+.\}
.el \{\
-. de MTO
-\\$2 \(laemail: \\$1 \(ra\\$3
+. ds la <\"
+. ds ra >\"
+. \" groff's man macros control hyphenation with this register.
+. nr HY 1
+.\}
+.
+.\" Start URL.
+.de UR
+. ds m1 \\$1\"
+. nh
+. if \\n(mH \{\
+. \" Start diversion in a new environment.
+. do ev URL-div
+. do di URL-div
+. \}
..
-. de URL
-\\$2 \(laURL: \\$1 \(ra\\$3
+.
+.
+.\" End URL.
+.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
+..
+.
+.
+.\" Start email address.
+.de MT
+. ds m1 \\$1\"
+. nh
+. if \\n(mH \{\
+. \" Start diversion in a new environment.
+. do ev URL-div
+. do di URL-div
+. \}
..
+.
+.
+.\" End email address.
+.de ME
+. 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=""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>"
+\&\\$*\"
+. \}
+. el \
+\\*(la\\*(m1\\*(ra\\$*\"
+.
+. hy \\n(HY
+..
+.\" --- End of lines taken from groff an-ext.tmac
.\}
.
-.TH GREP 1 \*(Dt "GNU grep @VERSION@" "User Commands"
.hy 0
.
.SH NAME
@@ -1174,11 +1277,17 @@ not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
.SH BUGS
.SS "Reporting Bugs"
Email bug reports to
-.MTO bug-grep@gnu.org "the bug-reporting address" .
+.MT bug-grep@gnu.org
+the bug-reporting address
+.ME .
An
-.URL http://lists.gnu.org/mailman/listinfo/bug-grep "email archive"
+.UR http://lists.gnu.org/mailman/listinfo/bug-grep
+email archive
+.UE
and a
-.URL http://debbugs.gnu.org/cgi/pkgreport.cgi?package=grep "bug tracker"
+.UR http://debbugs.gnu.org/cgi/pkgreport.cgi?package=grep
+bug tracker
+.UE
are available.
.SS "Known Bugs"
Large repetition counts in the
@@ -1206,7 +1315,9 @@ glob(7), regex(7).
grep(1p).
.SS "Full Documentation"
A
-.URL http://www.gnu.org/software/grep/manual/ "complete manual"
+.UR http://www.gnu.org/software/grep/manual/
+complete manual
+.UE
is available.
If the
.B info
--
2.14.3
