On Tue, Dec 20, 2022 at 06:24:45PM +0000, Klemens Nanni wrote:
>
> Feedback? OK?
>
ok, in general i'm fine with this. i do have some concerns though:
>
> 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
so first off i hate "Ar blah Ns s". i do understand why we might want
it, but i;d rather avoid it. it can make the text read better, but it
can also make it read worse (so i don;t think we should just slap it
on). and the formatting is truly yucky.
expr(1) is a good example. i think it doesn;t matter that expr can take
one arg or many. when we want to descrive it at its basic level, we just
want to say that it "evalautes expression". jumping through formatting
hoops to try and indicate that more than one expression is possible is
pointless. let's try and make the text clear and simple, and let
formatting come second. here's some ideas:
- The
.Nm
utility evaluates
.Ar expression
and writes ...
in this case we leave the reader to understand that SYNOPSIS and the
description all clearly show that more than one arg is possible. nice
and simple. this gets my vote.
- The
.Nm
utility evaluates one or more
.Ar expression
and writes ...
now we are spelling it out. it is less ambiguous than the first example,
but reads badly (one or more expression)
- The
.Nme
utility evaluates one or more expressions and writes ...
that reads better than the last example, but it misses the chance to
link "expression" as the argument name, and people will complain.
i am really ok with any of these. but i don;t like "Ar expression Ns s"
here because it both reads badly and formats ugly. i'm not saying we
can't use "Ar .* Ns s", just that we should think about not using it
willy nilly.
> 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 ...
it's no biggie i guess, but it was simpler on one line. what is gained
by splitting it?
> .Sh DESCRIPTION
> The
> .Nm
> utility splits
> .Ar file
> into pieces using the patterns
> -.Ar args .
> +.Ar arg Ns s .
i think we should just say "the pattern Ar arg".
> If
> .Ar file
> is
> @@ -92,7 +93,7 @@ created.
> .El
> .Pp
> The
> -.Ar args
> +.Ar arg Ns s
ditto
> 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
i would not use Ar in either of these (macro/argument) but i know it's
the firing squad for heresy
> 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
again, i would not mark this up
> 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,
i suppose text like this is showing us why the authors used "arguments"
rather than "argument". it is natural, in some cases. here i would
probably let the Ns s slide.
> 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 .
would not mark up
> 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 .
would not mark up
> 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
would not mark up
> 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 .
would not mark up
> If
> .Ar variable
> is already set,
> .Ar daemon Ns _ Ns Ar variable
> is reset to the optionally provided
> -.Ar arguments
> +.Ar argument Ns s
would not mark up
> 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 .
would not mark up
> 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"
>
after rereading my mail, i think what i want to say is i think we
sometimes tie ourselves in knots trying to make the text accoutn for
every eventuality. but i think it's simpler just to say what happens
normally, so people understand, then get in to the detail about well
this affects that, or this can be altered by doing that.
in another comparison, look at ls(1) (always a good one to pull out):
DESCRIPTION
For each operand that names a file of a type ...
no one would want
DESCRIPTION
For each operand that names any file/s/ of a type ...
like you can work out that more than one argument is possible. and when
you say up front what ls does, you don;t need to say that it can be
altered using the -x, -y, or -z options.
jmc
