From unknown Mon Jun 23 04:15:41 2025 X-Loop: help-debbugs@gnu.org Subject: bug#31228: Update GREP manpage Resent-From: "Laura Morales" Original-Sender: "Debbugs-submit" Resent-CC: bug-grep@gnu.org Resent-Date: Fri, 20 Apr 2018 16:26:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 31228 X-GNU-PR-Package: grep X-GNU-PR-Keywords: To: 31228@debbugs.gnu.org X-Debbugs-Original-To: bug-grep@gnu.org Received: via spool by submit@debbugs.gnu.org id=B.152424151420496 (code B ref -1); Fri, 20 Apr 2018 16:26:02 +0000 Received: (at submit) by debbugs.gnu.org; 20 Apr 2018 16:25:14 +0000 Received: from localhost ([127.0.0.1]:34320 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1f9YqX-0005KV-RF for submit@debbugs.gnu.org; Fri, 20 Apr 2018 12:25:14 -0400 Received: from eggs.gnu.org ([208.118.235.92]:39727) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1f9YVP-0004p2-W9 for submit@debbugs.gnu.org; Fri, 20 Apr 2018 12:03:25 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1f9YVJ-0000ma-7K for submit@debbugs.gnu.org; Fri, 20 Apr 2018 12:03:18 -0400 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=0.8 required=5.0 tests=BAYES_50,FREEMAIL_FROM autolearn=disabled version=3.3.2 Received: from lists.gnu.org ([2001:4830:134:3::11]:47429) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1f9YVJ-0000mU-5L for submit@debbugs.gnu.org; Fri, 20 Apr 2018 12:03:17 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:58888) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1f9YVH-0008Fi-Md for bug-grep@gnu.org; Fri, 20 Apr 2018 12:03:16 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1f9YVD-0000iM-UB for bug-grep@gnu.org; Fri, 20 Apr 2018 12:03:14 -0400 Received: from mout.gmx.com ([74.208.4.200]:33657) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1f9YVD-0000h1-NE for bug-grep@gnu.org; Fri, 20 Apr 2018 12:03:11 -0400 Received: from [87.5.185.142] ([87.5.185.142]) by 3c-app-mailcom-lxa13.server.lan (via HTTP); Fri, 20 Apr 2018 18:03:09 +0200 MIME-Version: 1.0 Message-ID: From: "Laura Morales" Content-Type: text/plain; charset=UTF-8 Date: Fri, 20 Apr 2018 18:03:09 +0200 Importance: normal Sensitivity: Normal X-Priority: 3 X-Provags-ID: V03:K1:y/W4YELXnwtEF9BgTEOVSnZEPmWFj+vG/nxiO4le2O2 IvCBouRlphi2fAXAX+HvP/20SKkVDxdh9M52dpi90X7/PJLIAX 33CLhVnjQsSLKThCiE1SqOMqIeTi/w0NmHZxigY38bbdhC2sES Tmv5dzagACQuwaNMhFq1O694SrhEpEJtVjDioAqaEk5RdJvo3m tX74zupNfUDOFJKbOLa9IElFXBeo1zLhSDWS8eFEyT7EffZphb vGxQ64E1uN8knXNCcW8iXsmHHkXX6yN+jbACZRpWT/jqg9ev4J ZGuuMk= X-UI-Out-Filterresults: notjunk:1;V01:K0:LE/3c32J2as=:oXyRs6EHIVIF/zLLQhun1T 5lcYqG5c5iKI7fXzThzXPHIgwx3s4S9VcJhxd7UOjNQ+Y8e0Swz1RJvAK/ODWtvr4vffAONKi 7P2X55KCIjnnS1EPQYyzBbr9g86i7ZQB/o+llu1rVUo4IkXMY7Ejao0VYMXWoaOsoe7aolPkl SBxXmDKaTIzYp8KUk0zN2e4iZ1oQ1Md3UyeCqJhSLNCOjY3BfjmkX2kduKfUedimSofPLbH11 I+8Jd2Pw1Xz+qOckN71Uah5bKrCU+ahEBMLDIR5HzD5Fp9wc7yaZfStYmukiS+ISosCRoGsJl 7MimvD0HkLgXxsNPNVAPf1mP9rTFPa37Oyvw1CDn3cGE5Q/awjitcAt/pStM/iJUW3yibdE4T RjWNQpmsSukdHuSdaOItEPjPe5X17eefuEmZIEFXytjgnPaVAnhjrxs894Cew+aGdAtReo9Tf ZAPrUKSRrfeII+xJag37DRk0V/W+dCRSMj1CmpdC9oFSmpAw2lLO X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] [fuzzy] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-Received-From: 2001:4830:134:3::11 X-Spam-Score: -4.1 (----) X-Mailman-Approved-At: Fri, 20 Apr 2018 12:25:12 -0400 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -5.1 (-----) 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 . An email archive and a bug tracker 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 bug-grep@gnu.org "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 From unknown Mon Jun 23 04:15:41 2025 X-Loop: help-debbugs@gnu.org Subject: bug#31228: Update GREP manpage Resent-From: Paul Eggert Original-Sender: "Debbugs-submit" Resent-CC: bug-grep@gnu.org Resent-Date: Fri, 20 Apr 2018 19:49:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 31228 X-GNU-PR-Package: grep X-GNU-PR-Keywords: To: Laura Morales Cc: 31228@debbugs.gnu.org Received: via spool by 31228-submit@debbugs.gnu.org id=B31228.15242537175548 (code B ref 31228); Fri, 20 Apr 2018 19:49:02 +0000 Received: (at 31228) by debbugs.gnu.org; 20 Apr 2018 19:48:37 +0000 Received: from localhost ([127.0.0.1]:34354 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1f9c1N-0001RQ-9X for submit@debbugs.gnu.org; Fri, 20 Apr 2018 15:48:37 -0400 Received: from zimbra.cs.ucla.edu ([131.179.128.68]:59756) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1f9c1I-0001R6-To for 31228@debbugs.gnu.org; Fri, 20 Apr 2018 15:48:33 -0400 Received: from localhost (localhost [127.0.0.1]) by zimbra.cs.ucla.edu (Postfix) with ESMTP id 246A0161631; Fri, 20 Apr 2018 12:48:27 -0700 (PDT) Received: from zimbra.cs.ucla.edu ([127.0.0.1]) by localhost (zimbra.cs.ucla.edu [127.0.0.1]) (amavisd-new, port 10032) with ESMTP id qSP0GJxrqc7g; Fri, 20 Apr 2018 12:48:25 -0700 (PDT) Received: from localhost (localhost [127.0.0.1]) by zimbra.cs.ucla.edu (Postfix) with ESMTP id 6640B161668; Fri, 20 Apr 2018 12:48:25 -0700 (PDT) X-Virus-Scanned: amavisd-new at zimbra.cs.ucla.edu Received: from zimbra.cs.ucla.edu ([127.0.0.1]) by localhost (zimbra.cs.ucla.edu [127.0.0.1]) (amavisd-new, port 10026) with ESMTP id L45BT0AvXC3x; Fri, 20 Apr 2018 12:48:25 -0700 (PDT) Received: from Penguin.CS.UCLA.EDU (Penguin.CS.UCLA.EDU [131.179.64.200]) by zimbra.cs.ucla.edu (Postfix) with ESMTPSA id 48580161631; Fri, 20 Apr 2018 12:48:25 -0700 (PDT) References: From: Paul Eggert Organization: UCLA Computer Science Department Message-ID: Date: Fri, 20 Apr 2018 12:48:25 -0700 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101 Thunderbird/52.7.0 MIME-Version: 1.0 In-Reply-To: Content-Type: multipart/mixed; boundary="------------ACC993DB0462B9F14BB7F43C" Content-Language: en-US X-Spam-Score: -2.3 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) This is a multi-part message in MIME format. --------------ACC993DB0462B9F14BB7F43C Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 7bit 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. --------------ACC993DB0462B9F14BB7F43C Content-Type: text/x-patch; name="0001-doc-port-better-to-mandoc.patch" Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename="0001-doc-port-better-to-mandoc.patch" >From fb9649338de86dc73bd5415b68d3ceeb99884905 Mon Sep 17 00:00:00 2001 From: Paul Eggert 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 "" +. \" Yes, strip off final newline of diversion and emit it. +. do chop URL-div +. do URL-div +\c +. do HTML-NS +. \} +. el \ +. do HTML-NS "\\*(m1" +\&\\$*\" +. \} +. 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 "" +. \" Yes, strip off final newline of diversion and emit it. +. do chop URL-div +. do URL-div +\c +. do HTML-NS +. \} +. el \ +. do HTML-NS "\\*(m1" +\&\\$*\" +. \} +. 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 --------------ACC993DB0462B9F14BB7F43C-- From unknown Mon Jun 23 04:15:41 2025 X-Loop: help-debbugs@gnu.org Subject: bug#31228: Update GREP manpage Resent-From: Ingo Schwarze Original-Sender: "Debbugs-submit" Resent-CC: bug-grep@gnu.org Resent-Date: Fri, 20 Apr 2018 23:07:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 31228 X-GNU-PR-Package: grep X-GNU-PR-Keywords: To: 31228@debbugs.gnu.org Cc: Laura Morales Received: via spool by 31228-submit@debbugs.gnu.org id=B31228.15242656056270 (code B ref 31228); Fri, 20 Apr 2018 23:07:01 +0000 Received: (at 31228) by debbugs.gnu.org; 20 Apr 2018 23:06:45 +0000 Received: from localhost ([127.0.0.1]:34427 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1f9f77-0001d4-D1 for submit@debbugs.gnu.org; Fri, 20 Apr 2018 19:06:45 -0400 Received: from scc-mailout-kit-02.scc.kit.edu ([129.13.231.82]:43067) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1f9ezo-0001RE-1c for 31228@debbugs.gnu.org; Fri, 20 Apr 2018 18:59:12 -0400 Received: from asta-nat.asta.uni-karlsruhe.de ([172.22.63.82] helo=hekate.usta.de) by scc-mailout-kit-02.scc.kit.edu with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (envelope-from ) id 1f9ezg-0007fE-AA; Sat, 21 Apr 2018 00:59:06 +0200 Received: from donnerwolke.usta.de ([172.24.96.3]) by hekate.usta.de with esmtp (Exim 4.77) (envelope-from ) id 1f9ezf-0007ly-T7; Sat, 21 Apr 2018 00:59:03 +0200 Received: from athene.usta.de ([172.24.96.10]) by donnerwolke.usta.de with esmtp (Exim 4.84_2) (envelope-from ) id 1f9ezg-0003ee-HJ; Sat, 21 Apr 2018 00:59:04 +0200 Received: from localhost (athene.usta.de [local]) by athene.usta.de (OpenSMTPD) with ESMTPA id 3132078a; Sat, 21 Apr 2018 00:59:03 +0200 (CEST) Date: Sat, 21 Apr 2018 00:59:03 +0200 From: Ingo Schwarze Message-ID: <20180420225903.GS64396@athene.usta.de> References: MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable In-Reply-To: User-Agent: Mutt/1.8.0 (2017-02-23) X-Spam-Score: -2.3 (--) X-Mailman-Approved-At: Fri, 20 Apr 2018 19:06:43 -0400 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) 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, =2Echop... 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 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D grep.in.1 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=20 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 /=08/ and bef= ore a +non-/=08/. When searching recursively, skip any subfile wh= ose base name matches _=08G_=08L_=08O_=08B; the base name is the part= after the last /=08/. - A pattern can use *=08*, ?=08?, and [=08[...]=08] as wildca= rds, and \=08\ to quote - a wildcard or backslash character literally. + A pattern can use *=08*, ?=08?, and [=08[...]=08] as wildcar= ds, and \=08\ to quote a + wildcard or backslash character literally. =20 -=08--=08-e=08ex=08xc=08cl=08lu=08ud=08de=08e-=08-f=08fr=08ro=08om= =08m=3D=08=3D_=08F_=08I_=08L_=08E 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 From unknown Mon Jun 23 04:15:41 2025 X-Loop: help-debbugs@gnu.org Subject: bug#31228: Update GREP manpage Resent-From: Paul Eggert Original-Sender: "Debbugs-submit" Resent-CC: bug-grep@gnu.org Resent-Date: Sat, 21 Apr 2018 20:56:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 31228 X-GNU-PR-Package: grep X-GNU-PR-Keywords: To: Ingo Schwarze , 31228@debbugs.gnu.org Received: via spool by 31228-submit@debbugs.gnu.org id=B31228.15243441306240 (code B ref 31228); Sat, 21 Apr 2018 20:56:01 +0000 Received: (at 31228) by debbugs.gnu.org; 21 Apr 2018 20:55:30 +0000 Received: from localhost ([127.0.0.1]:35196 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1f9zXc-0001cY-Gt for submit@debbugs.gnu.org; Sat, 21 Apr 2018 16:55:29 -0400 Received: from zimbra.cs.ucla.edu ([131.179.128.68]:38050) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1f9zXa-0001cK-0j for 31228@debbugs.gnu.org; Sat, 21 Apr 2018 16:55:26 -0400 Received: from localhost (localhost [127.0.0.1]) by zimbra.cs.ucla.edu (Postfix) with ESMTP id 236E616005C; Sat, 21 Apr 2018 13:55:20 -0700 (PDT) Received: from zimbra.cs.ucla.edu ([127.0.0.1]) by localhost (zimbra.cs.ucla.edu [127.0.0.1]) (amavisd-new, port 10032) with ESMTP id wctKhUzItDQd; Sat, 21 Apr 2018 13:55:18 -0700 (PDT) Received: from localhost (localhost [127.0.0.1]) by zimbra.cs.ucla.edu (Postfix) with ESMTP id 6E1EA160860; Sat, 21 Apr 2018 13:55:18 -0700 (PDT) X-Virus-Scanned: amavisd-new at zimbra.cs.ucla.edu Received: from zimbra.cs.ucla.edu ([127.0.0.1]) by localhost (zimbra.cs.ucla.edu [127.0.0.1]) (amavisd-new, port 10026) with ESMTP id 79S7Ie1bGPUr; Sat, 21 Apr 2018 13:55:18 -0700 (PDT) Received: from [192.168.1.9] (unknown [47.154.30.119]) by zimbra.cs.ucla.edu (Postfix) with ESMTPSA id 18A9016005C; Sat, 21 Apr 2018 13:55:18 -0700 (PDT) References: <20180420225903.GS64396@athene.usta.de> From: Paul Eggert Organization: UCLA Computer Science Department Message-ID: <6ca722fe-9621-8b10-279c-d81bd7928d5a@cs.ucla.edu> Date: Sat, 21 Apr 2018 13:55:17 -0700 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101 Thunderbird/52.7.0 MIME-Version: 1.0 In-Reply-To: <20180420225903.GS64396@athene.usta.de> Content-Type: multipart/mixed; boundary="------------EC2B928912AA77CA496B1E59" Content-Language: en-US X-Spam-Score: -2.3 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) This is a multi-part message in MIME format. --------------EC2B928912AA77CA496B1E59 Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: quoted-printable Ingo Schwarze wrote: > i admit that it requires a bit of work, but it would > give your users better manual pages We could add it to our list of things to do. In the meantime... > 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): That's a minor formatting glitch in the grep man page. Thanks for reporti= ng it.=20 I fixed it by installing the attached patch, which fixes some similar gli= tches=20 too. I installed a couple of other man page patches while in the neighbor= hood;=20 you can see the current version here: https://git.savannah.gnu.org/cgit/grep.git/plain/doc/grep.in.1 --------------EC2B928912AA77CA496B1E59 Content-Type: text/x-patch; name="0001-doc-man-page-format-fixes.patch" Content-Transfer-Encoding: quoted-printable Content-Disposition: attachment; filename="0001-doc-man-page-format-fixes.patch" =46rom 4c9732d40ffd7ffd280f551cecbe9a7c6fed054b Mon Sep 17 00:00:00 2001 From: Paul Eggert Date: Sat, 21 Apr 2018 12:00:54 -0700 Subject: [PATCH] doc: man-page format fixes * doc/grep.in.1: Fix minor formatting glitches, e.g., extra space after [...] because groff thought it was a sentence end. Problem reported by Ingo Schwarze (Bug#31228#11). --- doc/grep.in.1 | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/doc/grep.in.1 b/doc/grep.in.1 index ae14e54..8b6a85a 100644 --- a/doc/grep.in.1 +++ b/doc/grep.in.1 @@ -2,7 +2,7 @@ .de dT .ds Dt \\$2 .. -.dT Time-stamp: "2017-06-21" +.dT Time-stamp: "2018-04-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' @@ -620,7 +620,8 @@ Skip any command-line file with a name suffix that ma= tches the pattern using wildcard matching; a name suffix is either the whole name, or any suffix starting after a .B / -and before a +non-\fB/\fP. +and before a +.RI non- / . When searching recursively, skip any subfile whose base name matches .IR GLOB ; the base name is the part after the last @@ -629,7 +630,7 @@ A pattern can use .BR * , .BR ? , and -.BR [ ... ] +.BR [ .\|.\|. ]\& as wildcards, and .B \e to quote a wildcard or backslash character literally. @@ -800,7 +801,7 @@ Their names are self explanatory, and they are .BR [:space:] , .BR [:upper:] , and -.BR [:xdigit:]. +.BR [:xdigit:] . For example, .B [[:alnum:]] means the character class of numbers and @@ -1126,7 +1127,7 @@ The default is a cyan text foreground over the term= inal's default background. .B ne Boolean value that prevents clearing to the end of line using Erase in Line (EL) to Right -.RB ( \\\\\\33[K ) +.RB ( \e33[K ) each time a colorized item ends. This is needed on terminals on which EL is not supported. It is otherwise useful on terminals @@ -1139,7 +1140,7 @@ or when EL is too slow or causes too much flicker. The default is false (i.e., the capability is omitted). .PP Note that boolean capabilities have no -.BR =3D ... +.BR =3D .\|.\|.\& part. They are omitted (i.e., false) by default and become true when specified= =2E .PP @@ -1151,7 +1152,7 @@ and can be concatenated with semicolons. .B grep takes care of assembling the result into a complete SGR sequence -.RB ( \\\\\\33[ ... m ). +.RB ( \e33[ .\|.\|. m ). Common values to concatenate include .B 1 for bold, @@ -1269,7 +1270,7 @@ is used and a line is selected, the exit status is = 0 even if an error occurred. . .SH COPYRIGHT -Copyright 1998\(en2000, 2002, 2005\(en2017 Free Software Foundation, Inc= =2E +Copyright 1998\(en2000, 2002, 2005\(en2018 Free Software Foundation, Inc= =2E .PP This is free software; see the source for copying conditions. --=20 2.14.3 --------------EC2B928912AA77CA496B1E59-- From unknown Mon Jun 23 04:15:41 2025 X-Loop: help-debbugs@gnu.org Subject: bug#31228: Update GREP manpage Resent-From: Ingo Schwarze Original-Sender: "Debbugs-submit" Resent-CC: bug-grep@gnu.org Resent-Date: Sun, 22 Apr 2018 14:29:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 31228 X-GNU-PR-Package: grep X-GNU-PR-Keywords: To: Paul Eggert Cc: 31228@debbugs.gnu.org Received: via spool by 31228-submit@debbugs.gnu.org id=B31228.152440731119392 (code B ref 31228); Sun, 22 Apr 2018 14:29:02 +0000 Received: (at 31228) by debbugs.gnu.org; 22 Apr 2018 14:28:31 +0000 Received: from localhost ([127.0.0.1]:35945 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1fAFyh-00052i-5u for submit@debbugs.gnu.org; Sun, 22 Apr 2018 10:28:31 -0400 Received: from scc-mailout-kit-02.scc.kit.edu ([129.13.231.82]:42236) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1fAFyf-00052V-Lh for 31228@debbugs.gnu.org; Sun, 22 Apr 2018 10:28:30 -0400 Received: from asta-nat.asta.uni-karlsruhe.de ([172.22.63.82] helo=hekate.usta.de) by scc-mailout-kit-02.scc.kit.edu with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (envelope-from ) id 1fAFyY-0006CB-1h; Sun, 22 Apr 2018 16:28:23 +0200 Received: from donnerwolke.usta.de ([172.24.96.3]) by hekate.usta.de with esmtp (Exim 4.77) (envelope-from ) id 1fAFyW-0002Bx-E9; Sun, 22 Apr 2018 16:28:20 +0200 Received: from athene.usta.de ([172.24.96.10]) by donnerwolke.usta.de with esmtp (Exim 4.84_2) (envelope-from ) id 1fAFyX-0007If-2U; Sun, 22 Apr 2018 16:28:21 +0200 Received: from localhost (athene.usta.de [local]) by athene.usta.de (OpenSMTPD) with ESMTPA id c427f195; Sun, 22 Apr 2018 16:28:20 +0200 (CEST) Date: Sun, 22 Apr 2018 16:28:20 +0200 From: Ingo Schwarze Message-ID: <20180422142820.GF70576@athene.usta.de> References: <20180420225903.GS64396@athene.usta.de> <6ca722fe-9621-8b10-279c-d81bd7928d5a@cs.ucla.edu> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <6ca722fe-9621-8b10-279c-d81bd7928d5a@cs.ucla.edu> User-Agent: Mutt/1.8.0 (2017-02-23) X-Spam-Score: -2.3 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) Hi Paul, Paul Eggert wrote on Sat, Apr 21, 2018 at 01:55:17PM -0700: > Ingo Schwarze wrote: >> i admit that it requires a bit of work, but it would >> give your users better manual pages > We could add it to our list of things to do. In the meantime... Thanks. Totally reasonable and not urgent. >> 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): > That's a minor formatting glitch in the grep man page. > Thanks for reporting it. Heh. I didn't even view it as a glitch in the grep(1) manual, but you are right, there is nothing wrong with disambiguating it with "]\&" on the closing bracket. > I fixed it by installing the attached patch, which fixes some > similar glitches too. I installed a couple of other man page > patches while in the neighborhood; > you can see the current version here: > > https://git.savannah.gnu.org/cgit/grep.git/plain/doc/grep.in.1 I confirm that it now renders byte-by-byte identically with git-master groff and CVS-HEAD mandoc in -Tascii mode. While differences are not necessarily man page bugs, identical output is usually not a bad sign. > @@ -1126,7 +1127,7 @@ The default is a cyan text foreground over the terminal's default background. > .B ne > Boolean value that prevents clearing to the end of line > using Erase in Line (EL) to Right > -.RB ( \\\\\\33[K ) > +.RB ( \e33[K ) > each time a colorized item ends. > This is needed on terminals on which EL is not supported. > It is otherwise useful on terminals Excellent idea, i'm kind of surprised the old version actually worked... :-) Thanks again, Ingo From debbugs-submit-bounces@debbugs.gnu.org Wed Jan 01 02:40:52 2020 Received: (at control) by debbugs.gnu.org; 1 Jan 2020 07:40:52 +0000 Received: from localhost ([127.0.0.1]:35574 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1imYcd-0006KZ-Tu for submit@debbugs.gnu.org; Wed, 01 Jan 2020 02:40:52 -0500 Received: from zimbra.cs.ucla.edu ([131.179.128.68]:48562) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1imYcc-0006KK-Ku for control@debbugs.gnu.org; Wed, 01 Jan 2020 02:40:50 -0500 Received: from localhost (localhost [127.0.0.1]) by zimbra.cs.ucla.edu (Postfix) with ESMTP id 31D8F16008F for ; Tue, 31 Dec 2019 23:40:45 -0800 (PST) Received: from zimbra.cs.ucla.edu ([127.0.0.1]) by localhost (zimbra.cs.ucla.edu [127.0.0.1]) (amavisd-new, port 10032) with ESMTP id greSqD0ohnIE for ; Tue, 31 Dec 2019 23:40:44 -0800 (PST) Received: from localhost (localhost [127.0.0.1]) by zimbra.cs.ucla.edu (Postfix) with ESMTP id 986D916022A for ; Tue, 31 Dec 2019 23:40:44 -0800 (PST) X-Virus-Scanned: amavisd-new at zimbra.cs.ucla.edu Received: from zimbra.cs.ucla.edu ([127.0.0.1]) by localhost (zimbra.cs.ucla.edu [127.0.0.1]) (amavisd-new, port 10026) with ESMTP id QZig8YUwRQtc for ; Tue, 31 Dec 2019 23:40:44 -0800 (PST) Received: from [192.168.1.9] (cpe-23-242-74-103.socal.res.rr.com [23.242.74.103]) by zimbra.cs.ucla.edu (Postfix) with ESMTPSA id 7CB0A16008F for ; Tue, 31 Dec 2019 23:40:44 -0800 (PST) To: control@debbugs.gnu.org From: Paul Eggert Subject: 31228 is done Organization: UCLA Computer Science Department Message-ID: Date: Tue, 31 Dec 2019 23:40:44 -0800 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.2.2 MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Language: en-US Content-Transfer-Encoding: 7bit X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: control X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) close 31228 thanks This bug appears to be fixed, so closing it.