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

From: Paul Eggert <[email-masked]>
Date: Mon, 4 Nov 2024 13:56:18 -0800

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