12/20/22 20:16, Ingo Schwarze пишет:
> Hi Klemens,
>
> Jason McIntyre wrote on Tue, Dec 20, 2022 at 10:35:19AM +0000:
>> On Tue, Dec 20, 2022 at 09:36:39AM +0000, Klemens Nanni wrote:
>
>>> Both styles are used, but I argue that the former fails to distinguish
>>> between
>>> $ program 'args in one shell word'
>>> and
>>> $ program one arg per shell word
>>>
>>> It's a minor thing, imho, but perhaps we can decide for one and stick to
>>> it throughout the tree?
>>>
>>> Triple dots also make it immediately clear that many arguments may
>>> follow, no matter what the "arg"ument is named.
>>>
>>> Here's one examplatory diff for timeout(1).
>>>
>>> Feedback?
>
>> i prefer "arg ..." too.
>
> Seconded. Or rather, what, fourthed?
Thanks for the input.
>> by comparison, it would probably look weird to
>> write "files" instead of "file ...". indeed the Ar macro without args
>> outputs exactly that.
>>
>> still it would be good to get an idea of how many pages would be
>> affected by this.
>
> $ man -k Ar=args
>
> gives me a relatively short list, and the only clear offenders appear
> to be: doas(1), openssl(1), timeout(1), route(8), and possibly boot(8)
> on a handful of platforms.
>
> Strangely, in build-debug-info(1), cdio(1), csplit(1), tput(1),
> update-plist(1), ddb(4) we have "..." after plural "args" and i'm
> unsure what that is even intended to mean in some of the cases.
>
> I guess i ought to fix mdoc(7) myself.
Sure, I'll leave that for you.
>> if we have only a few pages using "args" it would seem to make sense.
>
> That seems to be the case. I think kn@ is welcome to go ahead and fix
> them - not in a completely mechanical way, of course, the text should
> still be clear and read well afterwards.
>
>> if it's 50/50 we might want to look for more complex
>
> Certainly not 50/50:
>
> $ man -k Ar=... | wc -l
>
> gives me well over three hundred pages.
>
>> examples and figure out whether all the change will be worth it.
>>
>> also some things will use argument vs arg. for example ssh(1). do you
>> propose to change those?
>
> $ man -k Ar=argument
>
> gives me fifty results.
Complete diff at the end for all tools I could find.
> I think that is a completely separate question [...]
Ack.
> There are also a handful of "Ar=arguments" that might deserve
> fixing, in particular su(1), tmux(1), bgpd.conf(5), bgpctl(8),
> and rcctl(8).
>
> And time(1) and btrace(8) might need
>
> .Ar arguments -> .Ar argument Ns s
>
> in the vein mentioned by millert@.
I've included these in the diff.
Feedback? OK?
Index: share/man/man4/ddb.4
===================================================================
RCS file: /cvs/src/share/man/man4/ddb.4,v
retrieving revision 1.104
diff -u -p -r1.104 ddb.4
--- share/man/man4/ddb.4 11 Sep 2022 06:38:11 -0000 1.104
+++ share/man/man4/ddb.4 20 Dec 2022 17:30:46 -0000
@@ -1018,7 +1018,7 @@ A synonym for
.Tg machine
.It Xo
.Ic mac Ns Op Ic hine
-.Ar subcommand Op Ar args ...
+.Ar subcommand Op Ar arg ...
.Xc
Perform a platform-specific command.
.Pp
Index: bin/expr/expr.1
===================================================================
RCS file: /cvs/src/bin/expr/expr.1,v
retrieving revision 1.24
diff -u -p -r1.24 expr.1
--- bin/expr/expr.1 16 Aug 2017 20:10:58 -0000 1.24
+++ bin/expr/expr.1 20 Dec 2022 17:31:39 -0000
@@ -12,12 +12,12 @@
.Nd evaluate expression
.Sh SYNOPSIS
.Nm expr
-.Ar expression
+.Ar expression ...
.Sh DESCRIPTION
The
.Nm
utility evaluates
-.Ar expression
+.Ar expression Ns s
and writes the result on standard output.
All operators are separate arguments to the
.Nm
Index: sbin/route/route.8
===================================================================
RCS file: /cvs/src/sbin/route/route.8,v
retrieving revision 1.106
diff -u -p -r1.106 route.8
--- sbin/route/route.8 19 Nov 2022 19:23:37 -0000 1.106
+++ sbin/route/route.8 20 Dec 2022 17:23:09 -0000
@@ -42,8 +42,8 @@
.Op Fl T Ar rtable
.Ar command
.Oo
-.Op Ar modifiers
-.Ar args
+.Op Ar modifier ...
+.Ar arg ...
.Oc
.Sh DESCRIPTION
.Nm
@@ -110,7 +110,7 @@ option.
.Op Fl T Ar rtable
.Tg
.Cm flush
-.Op Ar modifiers
+.Op Ar modifier ...
.Xc
Delete all gateway entries from the routing table.
When the address family is specified by any one of the
@@ -129,7 +129,7 @@ modifiers.
.Op Fl T Ar rtable
.Tg
.Cm get
-.Op Ar modifiers
+.Op Ar modifier ...
.Ar address
.Xc
Extract a routing entry from the kernel.
@@ -143,7 +143,7 @@ same address family as the destination a
.Op Fl T Ar rtable
.Tg
.Cm monitor
-.Op Ar modifiers
+.Op Ar modifier ...
.Xc
Continuously report any changes to the routing information base,
routing lookup misses, or suspected network partitionings.
@@ -278,7 +278,7 @@ have the syntax:
.Op Fl T Ar rtable
.Tg
.Cm add
-.Op Ar modifiers
+.Op Ar modifier ...
.Ar destination gateway
.Xc
.It Xo
@@ -287,7 +287,7 @@ have the syntax:
.Op Fl T Ar rtable
.Tg
.Cm change
-.Op Ar modifiers
+.Op Ar modifier ...
.Ar destination gateway
.Xc
.It Xo
@@ -297,7 +297,7 @@ have the syntax:
.Tg delete
.Tg
.Cm del Ns Op Cm ete
-.Op Ar modifiers
+.Op Ar modifier ...
.Ar destination gateway
.Xc
.El
Index: sbin/route/route.c
===================================================================
RCS file: /cvs/src/sbin/route/route.c,v
retrieving revision 1.260
diff -u -p -r1.260 route.c
--- sbin/route/route.c 10 Nov 2021 20:24:22 -0000 1.260
+++ sbin/route/route.c 20 Dec 2022 17:23:06 -0000
@@ -135,9 +135,9 @@ usage(char *cp)
warnx("botched keyword: %s", cp);
fprintf(stderr,
#ifndef SMALL
- "usage: %s [-dnqtv] [-T rtable] command [[modifiers] args]\n",
+ "usage: %s [-dnqtv] [-T rtable] command [[modifier ...] arg ...]\n",
#else
- "usage: %s [-dnqtv] command [[modifiers] args]\n",
+ "usage: %s [-dnqtv] command [[modifier ...] arg ...]\n",
#endif
__progname);
exit(1);
Index: usr.bin/cdio/cdio.1
===================================================================
RCS file: /cvs/src/usr.bin/cdio/cdio.1,v
retrieving revision 1.67
diff -u -p -r1.67 cdio.1
--- usr.bin/cdio/cdio.1 31 Mar 2022 17:27:24 -0000 1.67
+++ usr.bin/cdio/cdio.1 20 Dec 2022 17:17:52 -0000
@@ -40,7 +40,7 @@
.Op Fl sv
.Op Fl d Ar host : Ns Ar port
.Op Fl f Ar device
-.Op Ar command args ...
+.Op Ar command Op Ar arg ...
.Sh DESCRIPTION
The
.Nm
Index: usr.bin/cdio/cdio.c
===================================================================
RCS file: /cvs/src/usr.bin/cdio/cdio.c,v
retrieving revision 1.84
diff -u -p -r1.84 cdio.c
--- usr.bin/cdio/cdio.c 15 Feb 2022 08:17:50 -0000 1.84
+++ usr.bin/cdio/cdio.c 20 Dec 2022 17:18:39 -0000
@@ -227,7 +227,8 @@ help(void)
void
usage(void)
{
- fprintf(stderr, "usage: %s [-sv] [-d host:port] [-f device] [command
args ...]\n",
+ fprintf(stderr, "usage: %s [-sv] [-d host:port] [-f device] "
+ "[command [arg ...]]\n",
__progname);
exit(1);
}
Index: usr.bin/csplit/csplit.1
===================================================================
RCS file: /cvs/src/usr.bin/csplit/csplit.1,v
retrieving revision 1.12
diff -u -p -r1.12 csplit.1
--- usr.bin/csplit/csplit.1 24 Oct 2015 15:32:50 -0000 1.12
+++ usr.bin/csplit/csplit.1 20 Dec 2022 17:27:24 -0000
@@ -37,14 +37,15 @@
.Op Fl ks
.Op Fl f Ar prefix
.Op Fl n Ar number
-.Ar file args ...
+.Ar file
+.Ar arg ...
.Sh DESCRIPTION
The
.Nm
utility splits
.Ar file
into pieces using the patterns
-.Ar args .
+.Ar arg Ns s .
If
.Ar file
is
@@ -92,7 +93,7 @@ created.
.El
.Pp
The
-.Ar args
+.Ar arg Ns s
operands may be a combination of the following patterns:
.Bl -tag -width indent
.It Xo
Index: usr.bin/csplit/csplit.c
===================================================================
RCS file: /cvs/src/usr.bin/csplit/csplit.c,v
retrieving revision 1.10
diff -u -p -r1.10 csplit.c
--- usr.bin/csplit/csplit.c 8 Jul 2021 00:38:42 -0000 1.10
+++ usr.bin/csplit/csplit.c 20 Dec 2022 17:26:11 -0000
@@ -214,7 +214,7 @@ usage(void)
extern char *__progname;
fprintf(stderr,
- "usage: %s [-ks] [-f prefix] [-n number] file args ...\n",
+ "usage: %s [-ks] [-f prefix] [-n number] file arg ...\n",
__progname);
exit(1);
}
Index: usr.bin/doas/doas.1
===================================================================
RCS file: /cvs/src/usr.bin/doas/doas.1,v
retrieving revision 1.25
diff -u -p -r1.25 doas.1
--- usr.bin/doas/doas.1 16 Jan 2021 09:18:41 -0000 1.25
+++ usr.bin/doas/doas.1 20 Dec 2022 17:13:09 -0000
@@ -26,7 +26,7 @@
.Op Fl C Ar config
.Op Fl u Ar user
.Ar command
-.Op Ar args
+.Op Ar arg ...
.Sh DESCRIPTION
The
.Nm
Index: usr.bin/doas/doas.c
===================================================================
RCS file: /cvs/src/usr.bin/doas/doas.c,v
retrieving revision 1.97
diff -u -p -r1.97 doas.c
--- usr.bin/doas/doas.c 22 Mar 2022 20:36:49 -0000 1.97
+++ usr.bin/doas/doas.c 20 Dec 2022 17:13:31 -0000
@@ -40,7 +40,7 @@ static void __dead
usage(void)
{
fprintf(stderr, "usage: doas [-Lns] [-a style] [-C config] [-u user]"
- " command [args]\n");
+ " command [arg ...]\n");
exit(1);
}
Index: usr.bin/mandoc/mandoc.1
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/mandoc.1,v
retrieving revision 1.189
diff -u -p -r1.189 mandoc.1
--- usr.bin/mandoc/mandoc.1 2 Aug 2022 11:55:51 -0000 1.189
+++ usr.bin/mandoc/mandoc.1 20 Dec 2022 17:58:29 -0000
@@ -765,7 +765,7 @@ Messages displayed by
follow this format:
.Bd -ragged -offset indent
.Nm :
-.Ar file : Ns Ar line : Ns Ar column : level : message : macro arguments
+.Ar file : Ns Ar line : Ns Ar column : level : message : macro argument ...
.Pq Ar os
.Ed
.Pp
@@ -786,7 +786,7 @@ strings are explained below.
The name of the
.Ar macro
triggering the message and its
-.Ar arguments
+.Ar argument Ns s
are omitted where meaningless.
The
.Ar os
Index: usr.bin/openssl/openssl.1
===================================================================
RCS file: /cvs/src/usr.bin/openssl/openssl.1,v
retrieving revision 1.139
diff -u -p -r1.139 openssl.1
--- usr.bin/openssl/openssl.1 19 Jul 2022 16:08:09 -0000 1.139
+++ usr.bin/openssl/openssl.1 20 Dec 2022 17:35:52 -0000
@@ -119,8 +119,8 @@
.Sh SYNOPSIS
.Nm
.Ar command
-.Op Ar command_opts
-.Op Ar command_args
+.Op Ar command_opt ...
+.Op Ar command_arg ...
.Pp
.Nm
.Cm list-standard-commands |
Index: usr.bin/su/su.1
===================================================================
RCS file: /cvs/src/usr.bin/su/su.1,v
retrieving revision 1.37
diff -u -p -r1.37 su.1
--- usr.bin/su/su.1 8 Jul 2020 16:05:27 -0000 1.37
+++ usr.bin/su/su.1 20 Dec 2022 17:49:51 -0000
@@ -42,7 +42,7 @@
.Op Fl a Ar auth-type
.Op Fl c Ar login-class
.Op Fl s Ar login-shell
-.Op Ar login Op Ar "shell arguments"
+.Op Ar login Op Ar shell-argument ...
.Ek
.Sh DESCRIPTION
The
@@ -168,8 +168,8 @@ and
options are mutually exclusive; the last one specified
overrides any previous ones.
.Pp
-If the optional
-.Ar "shell arguments"
+If
+.Ar shell-argument Ns s
are provided on the command line, they are passed to the login shell of
the target login.
This allows it to pass arbitrary commands via the
Index: usr.bin/su/su.c
===================================================================
RCS file: /cvs/src/usr.bin/su/su.c,v
retrieving revision 1.88
diff -u -p -r1.88 su.c
--- usr.bin/su/su.c 23 Mar 2022 02:18:22 -0000 1.88
+++ usr.bin/su/su.c 20 Dec 2022 17:48:18 -0000
@@ -487,7 +487,7 @@ usage(void)
fprintf(stderr, "usage: %s [-fKLlm] [-a auth-type] [-c login-class] "
"[-s login-shell]\n"
- "%-*s[login [shell arguments]]\n", __progname,
+ "%-*s[login [shell-argument ...]]\n", __progname,
(int)strlen(__progname) + 8, "");
exit(1);
}
Index: usr.bin/time/time.1
===================================================================
RCS file: /cvs/src/usr.bin/time/time.1,v
retrieving revision 1.21
diff -u -p -r1.21 time.1
--- usr.bin/time/time.1 1 Jan 2019 16:17:03 -0000 1.21
+++ usr.bin/time/time.1 20 Dec 2022 17:53:54 -0000
@@ -46,7 +46,7 @@
executes and times
.Ar utility
with optional
-.Ar arguments .
+.Ar argument Ns s .
After the
.Ar utility
finishes,
Index: usr.bin/timeout/timeout.1
===================================================================
RCS file: /cvs/src/usr.bin/timeout/timeout.1,v
retrieving revision 1.3
diff -u -p -r1.3 timeout.1
--- usr.bin/timeout/timeout.1 4 Sep 2021 11:58:31 -0000 1.3
+++ usr.bin/timeout/timeout.1 20 Dec 2022 17:14:36 -0000
@@ -41,14 +41,12 @@
.Op Fl -preserve-status
.Ar duration
.Ar command
-.Op Ar args
+.Op Ar arg ...
.Sh DESCRIPTION
The
.Nm
utility executes
-.Ar command ,
-with any
-.Ar args ,
+.Ar command
and kills it if it is still running after the
specified
.Ar duration .
Index: usr.bin/timeout/timeout.c
===================================================================
RCS file: /cvs/src/usr.bin/timeout/timeout.c,v
retrieving revision 1.21
diff -u -p -r1.21 timeout.c
--- usr.bin/timeout/timeout.c 2 Jul 2022 19:00:35 -0000 1.21
+++ usr.bin/timeout/timeout.c 20 Dec 2022 17:14:52 -0000
@@ -57,7 +57,7 @@ usage(void)
fprintf(stderr,
"usage: timeout [-k time] [-s sig] [--foreground]"
" [--preserve-status] duration\n"
- " command [args]\n");
+ " command [arg ...]\n");
exit(1);
}
Index: usr.bin/tmux/tmux.1
===================================================================
RCS file: /cvs/src/usr.bin/tmux/tmux.1,v
retrieving revision 1.909
diff -u -p -r1.909 tmux.1
--- usr.bin/tmux/tmux.1 16 Dec 2022 08:13:40 -0000 1.909
+++ usr.bin/tmux/tmux.1 20 Dec 2022 18:03:28 -0000
@@ -961,7 +961,7 @@ Will run
directly without invoking the shell.
.Pp
.Ar command
-.Op Ar arguments
+.Op Ar argument ...
refers to a
.Nm
command, either passed with the command and arguments separately, for example:
@@ -1538,8 +1538,7 @@ show debugging information about jobs an
.Tg source
.It Xo Ic source-file
.Op Fl Fnqv
-.Ar path
-.Ar ...
+.Ar path ...
.Xc
.D1 Pq alias: Ic source
Execute commands from one or more files specified by
@@ -3120,7 +3119,7 @@ Commands related to key bindings are as
.Op Fl nr
.Op Fl N Ar note
.Op Fl T Ar key-table
-.Ar key command Op Ar arguments
+.Ar key command Op Ar argument ...
.Xc
.D1 Pq alias: Ic bind
Bind key
@@ -3216,7 +3215,7 @@ lists the command for keys that do not h
.Op Fl c Ar target-client
.Op Fl N Ar repeat-count
.Op Fl t Ar target-pane
-.Ar key Ar ...
+.Ar key ...
.Xc
.D1 Pq alias: Ic send
Send a key or keys to a window or client.
@@ -5821,8 +5820,7 @@ until it is dismissed.
.Op Fl y Ar position
.Ar name
.Ar key
-.Ar command
-.Ar ...
+.Ar command Op Ar argument ...
.Xc
.D1 Pq alias: Ic menu
Display a menu on
Index: usr.bin/tput/tput.1
===================================================================
RCS file: /cvs/src/usr.bin/tput/tput.1,v
retrieving revision 1.25
diff -u -p -r1.25 tput.1
--- usr.bin/tput/tput.1 25 Jul 2022 02:25:56 -0000 1.25
+++ usr.bin/tput/tput.1 20 Dec 2022 17:33:35 -0000
@@ -41,7 +41,7 @@
.Nm tput
.Op Fl T Ar term
.Ar attribute
-.Op Ar attribute-args
+.Op Ar attribute-arg ...
.Ar ...
.Nm tput
.Op Fl T Ar term
Index: usr.bin/tput/tput.c
===================================================================
RCS file: /cvs/src/usr.bin/tput/tput.c,v
retrieving revision 1.25
diff -u -p -r1.25 tput.c
--- usr.bin/tput/tput.c 4 Dec 2022 23:50:49 -0000 1.25
+++ usr.bin/tput/tput.c 20 Dec 2022 17:33:51 -0000
@@ -390,7 +390,7 @@ usage(void)
(void)fprintf(stderr, "usage: %s [-T term]\n", __progname);
else
(void)fprintf(stderr,
- "usage: %s [-T term] attribute [attribute-args] ...\n"
+ "usage: %s [-T term] attribute [attribute-arg ...] ...\n"
" %s [-T term] -S\n", __progname, __progname);
exit(1);
}
Index: usr.sbin/bgpctl/bgpctl.8
===================================================================
RCS file: /cvs/src/usr.sbin/bgpctl/bgpctl.8,v
retrieving revision 1.102
diff -u -p -r1.102 bgpctl.8
--- usr.sbin/bgpctl/bgpctl.8 17 Oct 2022 15:04:12 -0000 1.102
+++ usr.sbin/bgpctl/bgpctl.8 20 Dec 2022 17:51:20 -0000
@@ -127,21 +127,21 @@ Bring the BGP session to the specified n
may be the neighbor's address, description or the word
.Cm group
followed by a group description.
-.It Cm network add Ar prefix Op Ar arguments
+.It Cm network add Ar prefix Op Ar argument ...
Add the specified prefix to the list of announced networks.
It is possible to set various path attributes with additional
-.Ar arguments .
+.Ar argument Ns s .
Adding a prefix will replace an existing equal prefix, including
prefixes loaded from the configuration.
.It Xo
.Cm network bulk
-.Op Ar arguments
+.Op Ar argument ...
.Op Cm add
.Xc
Bulk add specified prefixes to the list of announced networks.
Prefixes should be sent via stdin.
It is possible to set various path attributes with additional
-.Ar arguments .
+.Ar argument Ns s .
If neither
.Cm add
or
Index: usr.sbin/bgpd/bgpd.conf.5
===================================================================
RCS file: /cvs/src/usr.sbin/bgpd/bgpd.conf.5,v
retrieving revision 1.226
diff -u -p -r1.226 bgpd.conf.5
--- usr.sbin/bgpd/bgpd.conf.5 21 Jul 2022 12:34:19 -0000 1.226
+++ usr.sbin/bgpd/bgpd.conf.5 20 Dec 2022 17:53:14 -0000
@@ -730,7 +730,7 @@ More than one
.Ic import-target
can be specified.
.Pp
-.It Ic network Ar arguments ...
+.It Ic network Ar argument ...
Announce the given networks within this VPN;
see the
.Sx NETWORK ANNOUNCEMENTS
Index: usr.sbin/btrace/btrace.8
===================================================================
RCS file: /cvs/src/usr.sbin/btrace/btrace.8,v
retrieving revision 1.7
diff -u -p -r1.7 btrace.8
--- usr.sbin/btrace/btrace.8 1 May 2022 20:23:11 -0000 1.7
+++ usr.sbin/btrace/btrace.8 20 Dec 2022 17:54:17 -0000
@@ -35,7 +35,7 @@ It interprets the
program in
.Ar file
with optional
-.Ar arguments
+.Ar argument Ns s
and communicates with the dynamic tracer device using the interface described
in
.Xr dt 4 .
.Pp
Index: usr.sbin/rcctl/rcctl.8
===================================================================
RCS file: /cvs/src/usr.sbin/rcctl/rcctl.8,v
retrieving revision 1.42
diff -u -p -r1.42 rcctl.8
--- usr.sbin/rcctl/rcctl.8 13 Sep 2022 06:20:38 -0000 1.42
+++ usr.sbin/rcctl/rcctl.8 20 Dec 2022 17:41:46 -0000
@@ -23,7 +23,7 @@
.Sh SYNOPSIS
.Nm rcctl
.Cm get Ns | Ns Cm getdef Ns | Ns Cm set
-.Ar service | daemon Op Ar variable Op Ar arguments
+.Ar service | daemon Op Ar variable Op Ar argument ...
.Nm rcctl
.Op Fl df
.Sm off
@@ -146,17 +146,17 @@ command is only needed after enabling a
that needs to run before one or more already enabled daemons.
Specify the new daemon preceded by all that need to run before it,
but not the ones depending on it.
-.It Cm set Ar service | daemon variable Op Ar arguments
+.It Cm set Ar service | daemon variable Op Ar argument ...
For a daemon, set the variable
.Ar daemon Ns _ Ns Ar variable
to the specified
-.Ar arguments .
+.Ar argument Ns s .
If
.Ar variable
is already set,
.Ar daemon Ns _ Ns Ar variable
is reset to the optionally provided
-.Ar arguments
+.Ar argument Ns s
or to its default value.
.Pp
The
@@ -166,7 +166,7 @@ must be provided with the
.Cm on
or
.Cm off
-.Ar arguments .
+.Ar argument Ns s .
It is used to enable or disable
.Ar service
or
Index: usr.sbin/rcctl/rcctl.sh
===================================================================
RCS file: /cvs/src/usr.sbin/rcctl/rcctl.sh,v
retrieving revision 1.114
diff -u -p -r1.114 rcctl.sh
--- usr.sbin/rcctl/rcctl.sh 1 Sep 2022 07:25:32 -0000 1.114
+++ usr.sbin/rcctl/rcctl.sh 20 Dec 2022 17:43:01 -0000
@@ -32,7 +32,7 @@ usage()
for _i in ${_rc_actions}; do _a="$(echo -n ${_i}${_a:+|${_a}})"; done
_rc_err \
- "usage: rcctl get|getdef|set service | daemon [variable [arguments]]
+ "usage: rcctl get|getdef|set service | daemon [variable [argument ...]]
rcctl [-df] ${_a} daemon ...
rcctl disable|enable|order [daemon ...]
rcctl ls all|failed|off|on|rogue|started|stopped"
