Subject: bug#74205: closed (Re: bug#74205: man: dots and closing bracket in wrong order)

From: [email-masked] (GNU bug Tracking System)
Date: Mon, 04 Nov 2024 21:57:02 +0000

Your bug report

#74205: man: dots and closing bracket in wrong order

which was filed against the grep package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to [email-masked].

-- 
74205: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=74205
GNU Bug Tracking System
Contact [email-masked] with problems

Subject: Re: bug#74205: man: dots and closing bracket in wrong order
From: Paul Eggert <[email-masked]>
To: Martin Schulte <[email-masked]>
Cc: [email-masked]
Date: Mon, 4 Nov 2024 13:56:18 -0800
List-Id: <debbugs-submit.debbugs.gnu.org>

On 2024-11-04 12:28, Martin Schulte wrote:
> the dots and the closing are in the wrong order compared to "all" other man pages:

POSIX uses yet another style for ... and []; see:

https://pubs.opengroup.org/onlinepubs/9799919799/utilities/grep.html

That being said, it's a bit nicer if grep matches similar GNU apps 
(regardless of what POSIX does) so I installed the attached patch to try 
to do that. Thanks for mentioning the issue.

From 24deafb92fd8249be46f0f8f8358c604cd5476db Mon Sep 17 00:00:00 2001
From: Paul Eggert <[email-masked]>
Date: Mon, 4 Nov 2024 13:52:00 -0800
Subject: [PATCH] =?UTF-8?q?doc:=20more=20consistent=20style=20for=20?=
 =?UTF-8?q?=E2=80=98...=E2=80=99?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Problem reported by Martin Schulte <https://bugs.gnu.org/74205>.
* doc/grep.in.1, doc/grep.texi:
Use a more consistent style for [OPTION]... and [FILE]... in usage.
This doesn’t match what POSIX does but seems to be common in GNU doc.
Also, ‘...’ -> ‘@dots{}’ in grep.texi.
---
 doc/grep.in.1 | 21 ++++++++++++---------
 doc/grep.texi |  8 ++++----
 2 files changed, 16 insertions(+), 13 deletions(-)

diff --git a/doc/grep.in.1 b/doc/grep.in.1
index d9604ae..29a55ad 100644
--- a/doc/grep.in.1
+++ b/doc/grep.in.1
@@ -142,30 +142,33 @@ grep \- print lines that match patterns
 .
 .SH SYNOPSIS
 .B grep
-.RI [ OPTION .\|.\|.]\&
+.RI [ OPTION ].\|.\|.\&
 .I PATTERNS
-.RI [ FILE .\|.\|.]
+.RI [ FILE ].\|.\|.
 .br
 .B grep
-.RI [ OPTION .\|.\|.]\&
+.RI [ OPTION ].\|.\|.\&
 .B \-e
 .I PATTERNS
 \&.\|.\|.\&
-.RI [ FILE .\|.\|.]
+.RI [ FILE ].\|.\|.
 .br
 .B grep
-.RI [ OPTION .\|.\|.]\&
+.RI [ OPTION ].\|.\|.\&
 .B \-f
 .I PATTERN_FILE
 \&.\|.\|.\&
-.RI [ FILE .\|.\|.]
+.RI [ FILE ].\|.\|.
 .
 .SH DESCRIPTION
 .B grep
-searches for
-.I PATTERNS
-in each
+searches for patterns in each
 .IR FILE .
+In the synopsis's first form, which is used if no
+.B \-e
+or
+.B \-f
+options are present, the first operand
 .I PATTERNS
 is one or more patterns separated by newline characters, and
 .B grep
diff --git a/doc/grep.texi b/doc/grep.texi
index 9c46e76..8495919 100644
--- a/doc/grep.texi
+++ b/doc/grep.texi
@@ -109,7 +109,7 @@ there is no way to match newline characters in a text.
 The general synopsis of the @command{grep} command line is
 
 @example
-grep [@var{option}...] [@var{patterns}] [@var{file}...]
+grep [@var{option}]@dots{} [@var{patterns}] [@var{file}]@dots{}
 @end example
 
 @noindent
@@ -714,7 +714,7 @@ immediately after a slash (@samp{/}) in the name.
 When searching recursively, skip any subfile whose base
 name matches @var{glob}; the base name is the part after the last
 slash.  A pattern can use
-@samp{*}, @samp{?}, and @samp{[}...@samp{]} as wildcards,
+@samp{*}, @samp{?}, and @samp{[}@dots{}@samp{]} as wildcards,
 and @code{\} to quote a wildcard or backslash character literally.
 
 @item --exclude-from=@var{file}
@@ -903,7 +903,7 @@ for permitted values and their meanings as character attributes.)
 These substring values are integers in decimal representation
 and can be concatenated with semicolons.
 @command{grep} takes care of assembling the result
-into a complete SGR sequence (@samp{\33[}...@samp{m}).
+into a complete SGR sequence (@samp{\33[}@dots{}@samp{m}).
 Common values to concatenate include
 @samp{1} for bold,
 @samp{4} for underline,
@@ -1016,7 +1016,7 @@ or when EL is too slow or causes too much flicker.
 The default is false (i.e., the capability is omitted).
 @end table
 
-Note that boolean capabilities have no @samp{=}... part.
+Note that boolean capabilities have no @samp{=}@dots{} part.
 They are omitted (i.e., false) by default and become true when specified.

-- 
2.43.0

Subject: man: dots and closing bracket in wrong order
From: Martin Schulte <[email-masked]>
To: [email-masked]
Date: Mon, 4 Nov 2024 21:28:39 +0100
List-Id: <debbugs-submit.debbugs.gnu.org>

Hello,

it doesn't harm but I always stumple when I read the SYNOPSIS in grep's man page where - in contrast to the usage message - the dots and the closing are in the wrong order compared to "all" other man pages:

$ man grep | head
GREP(1)                         User Commands                        GREP(1)

NAME
       grep, egrep, fgrep, rgrep - print lines that match patterns

SYNOPSIS
       grep [OPTION...] PATTERNS [FILE...]
       grep [OPTION...] -e PATTERNS ... [FILE...]
       grep [OPTION...] -f PATTERN_FILE ... [FILE...]

$ grep
Usage: grep [OPTION]... PATTERNS [FILE]...
Try 'grep --help' for more information.

Best regards

Martin