ldomctl: improve usage

classic Classic list List threaded Threaded
14 messages Options
Reply | Threaded
Open this post in threaded view
|

ldomctl: improve usage

Klemens Nanni-2
ldomctl(8) describes much more commands than the poor usage:

        $ ldomctl
        usage: ldomctl start|stop|panic domain
               ldomctl status [domain]

Doing as vmctl already does, this diff turns it into

        usage: ldomctl command [argument ...]
                ldomctl delete configuration
                ldomctl download directory
                ldomctl dump
                ldomctl init-system file
                ldomctl list
                ldomctl panic domain
                ldomctl select configuration
                ldomctl start domain
                ldomctl status [domain]
                ldomctl stop domain

The order of this output is lexicographically sorted exactly as in the
manual page.

OK?

Index: usr.sbin/ldomctl/ldomctl.c
===================================================================
RCS file: /cvs/src/usr.sbin/ldomctl/ldomctl.c,v
retrieving revision 1.21
diff -u -p -r1.21 ldomctl.c
--- usr.sbin/ldomctl/ldomctl.c 15 Sep 2018 13:20:16 -0000 1.21
+++ usr.sbin/ldomctl/ldomctl.c 22 Jun 2019 16:10:40 -0000
@@ -37,6 +37,7 @@ extern struct ds_service pri_service;
 struct command {
  const char *cmd_name;
  void (*cmd_func)(int, char **);
+ const char *usage;
 };
 
 __dead void usage(void);
@@ -59,17 +60,17 @@ void guest_status(int argc, char **argv)
 void init_system(int argc, char **argv);
 
 struct command commands[] = {
- { "download", download },
- { "dump", dump },
- { "list", list },
- { "select", xselect },
- { "delete", delete },
- { "start", guest_start },
- { "stop", guest_stop },
- { "panic", guest_panic },
- { "status", guest_status },
- { "init-system", init_system },
- { NULL, NULL }
+ { "delete", delete, "configuration" },
+ { "download", download, "directory" },
+ { "dump", dump, "" },
+ { "init-system", init_system, "file" },
+ { "list", list, "" },
+ { "panic", guest_panic, "domain" },
+ { "select", xselect, "configuration" },
+ { "start", guest_start, "domain" },
+ { "status", guest_status, "[domain]" },
+ { "stop", guest_stop, "domain" },
+ { NULL }
 };
 
 void hv_open(void);
@@ -158,9 +159,13 @@ void
 usage(void)
 {
  extern char *__progname;
+ int i;
 
- fprintf(stderr, "usage: %s start|stop|panic domain\n", __progname);
- fprintf(stderr, "       %s status [domain]\n", __progname);
+ fprintf(stderr, "usage:\t%s command [argument ...]\n", __progname);
+ for (i = 0; commands[i].cmd_name != NULL; i++) {
+ fprintf(stderr, "\t%s %s %s\n", __progname,
+    commands[i].cmd_name, commands[i].usage);
+ }
  exit(EXIT_FAILURE);
 }
 

Reply | Threaded
Open this post in threaded view
|

Re: ldomctl: improve usage

Mark Kettenis
> Date: Sat, 22 Jun 2019 18:35:27 +0200
> From: Klemens Nanni <[hidden email]>
>
> ldomctl(8) describes much more commands than the poor usage:
>
> $ ldomctl
> usage: ldomctl start|stop|panic domain
>       ldomctl status [domain]
>
> Doing as vmctl already does, this diff turns it into
>
> usage: ldomctl command [argument ...]
> ldomctl delete configuration
> ldomctl download directory
> ldomctl dump
> ldomctl init-system file
> ldomctl list
> ldomctl panic domain
> ldomctl select configuration
> ldomctl start domain
> ldomctl status [domain]
> ldomctl stop domain
>
> The order of this output is lexicographically sorted exactly as in the
> manual page.
>
> OK?

Not sure such a long list is actually useful, but sure.

> Index: usr.sbin/ldomctl/ldomctl.c
> ===================================================================
> RCS file: /cvs/src/usr.sbin/ldomctl/ldomctl.c,v
> retrieving revision 1.21
> diff -u -p -r1.21 ldomctl.c
> --- usr.sbin/ldomctl/ldomctl.c 15 Sep 2018 13:20:16 -0000 1.21
> +++ usr.sbin/ldomctl/ldomctl.c 22 Jun 2019 16:10:40 -0000
> @@ -37,6 +37,7 @@ extern struct ds_service pri_service;
>  struct command {
>   const char *cmd_name;
>   void (*cmd_func)(int, char **);
> + const char *usage;
>  };
>  
>  __dead void usage(void);
> @@ -59,17 +60,17 @@ void guest_status(int argc, char **argv)
>  void init_system(int argc, char **argv);
>  
>  struct command commands[] = {
> - { "download", download },
> - { "dump", dump },
> - { "list", list },
> - { "select", xselect },
> - { "delete", delete },
> - { "start", guest_start },
> - { "stop", guest_stop },
> - { "panic", guest_panic },
> - { "status", guest_status },
> - { "init-system", init_system },
> - { NULL, NULL }
> + { "delete", delete, "configuration" },
> + { "download", download, "directory" },
> + { "dump", dump, "" },
> + { "init-system", init_system, "file" },
> + { "list", list, "" },
> + { "panic", guest_panic, "domain" },
> + { "select", xselect, "configuration" },
> + { "start", guest_start, "domain" },
> + { "status", guest_status, "[domain]" },
> + { "stop", guest_stop, "domain" },
> + { NULL }
>  };
>  
>  void hv_open(void);
> @@ -158,9 +159,13 @@ void
>  usage(void)
>  {
>   extern char *__progname;
> + int i;
>  
> - fprintf(stderr, "usage: %s start|stop|panic domain\n", __progname);
> - fprintf(stderr, "       %s status [domain]\n", __progname);
> + fprintf(stderr, "usage:\t%s command [argument ...]\n", __progname);
> + for (i = 0; commands[i].cmd_name != NULL; i++) {
> + fprintf(stderr, "\t%s %s %s\n", __progname,
> +    commands[i].cmd_name, commands[i].usage);
> + }
>   exit(EXIT_FAILURE);
>  }
>  
>
>

Reply | Threaded
Open this post in threaded view
|

Re: ldomctl: improve usage

Theo de Raadt-2
In reply to this post by Klemens Nanni-2
Klemens Nanni <[hidden email]> wrote:

> ldomctl(8) describes much more commands than the poor usage:
>
> $ ldomctl
> usage: ldomctl start|stop|panic domain
>       ldomctl status [domain]
>
> Doing as vmctl already does, this diff turns it into
>
> usage: ldomctl command [argument ...]
> ldomctl delete configuration
> ldomctl download directory
> ldomctl dump
> ldomctl init-system file
> ldomctl list
> ldomctl panic domain
> ldomctl select configuration
> ldomctl start domain
> ldomctl status [domain]
> ldomctl stop domain
>
> The order of this output is lexicographically sorted exactly as in the
> manual page.

I'm not happy with usage messages which fill half a screen.  There has
to be some threshold where we include very little information, and force
people to the manual page instead.  The many *ctl programs stradle this
threshold and while I understand the desire for a better usage message,
I think this is heading too far in the wrong direction.

Reply | Threaded
Open this post in threaded view
|

Re: ldomctl: improve usage

Klemens Nanni-2
In reply to this post by Mark Kettenis
On Sat, Jun 22, 2019 at 07:00:53PM +0200, Mark Kettenis wrote:
> Not sure such a long list is actually useful, but sure.
I'd argue it is complete and consistent.  Both `man -h ldomctl' and
`ldomctl [-h]' would lack information, so there was no way of getting
a quick overview without reading the entire manual.

Reply | Threaded
Open this post in threaded view
|

Re: ldomctl: improve usage

Theo de Raadt-2
Klemens Nanni <[hidden email]> wrote:

> On Sat, Jun 22, 2019 at 07:00:53PM +0200, Mark Kettenis wrote:
> > Not sure such a long list is actually useful, but sure.
> I'd argue it is complete and consistent.  Both `man -h ldomctl' and
> `ldomctl [-h]' would lack information, so there was no way of getting
> a quick overview without reading the entire manual.

Sure there is a quick overview!  Obviously, the existing usage hints
that things are complicated, and a manu page consultation is required.

Many many commands have incomplete usage, thereby leading you to the
manual page.

On the other hand, spamming 1/4 of a screen during incorrect usage
risks damaging the user's understanding of context.

I can give a few crazy examples: ld, cc, ksh.  I'll say again, there
surely are cases where it is pointless making usage be complete, because
the compleness can be harmful.  Is this one?  Maybe...

Reply | Threaded
Open this post in threaded view
|

Re: ldomctl: improve usage

Klemens Nanni-2
In reply to this post by Theo de Raadt-2
On Sat, Jun 22, 2019 at 11:05:00AM -0600, Theo de Raadt wrote:
> I'm not happy with usage messages which fill half a screen.  There has
> to be some threshold where we include very little information, and force
> people to the manual page instead.  The many *ctl programs stradle this
> threshold and while I understand the desire for a better usage message,
> I think this is heading too far in the wrong direction.
vmctl and ldomctl seem to be the only two control programs with such
extensive usage;  I appreciate this it does indeed helps me faster and
more effectively than reading the manual.

gpioctl is on the same path with five lines, the rest of *ctl I glanced
over either shows one (long) synopsis a la pfctl or uses an entirely
different approach as seen with bgpctl.

Neither of those make sense here I think.  While I agree with you that
a certain threshold of complexity requires reading the manual, but I
do not think this go with limiting terse information in the usage.

Reply | Threaded
Open this post in threaded view
|

Re: ldomctl: improve usage

Theo de Raadt-2
In reply to this post by Theo de Raadt-2
Theo de Raadt <[hidden email]> wrote:
> I can give a few crazy examples: ld, cc, ksh.  I'll say again, there
> surely are cases where it is pointless making usage be complete, because
> the compleness can be harmful.  Is this one?  Maybe...

I've been burned a few times by bgpctl having such a long usage.

# bgpctl
missing argument:
valid commands/args:
  reload
  show
  fib
  neighbor
  network
  irrfilter
  log

The problem is when I'm on screens that don't have scroll-back, those 9
lines have scrolled other information off the top, and then I've had to
repeat the operations, or if not possible, been more frustrated.

Reply | Threaded
Open this post in threaded view
|

Re: ldomctl: improve usage

Klemens Nanni-2
In reply to this post by Theo de Raadt-2
On Sat, Jun 22, 2019 at 11:16:59AM -0600, Theo de Raadt wrote:
> I can give a few crazy examples: ld, cc, ksh.  I'll say again, there
> surely are cases where it is pointless making usage be complete, because
> the compleness can be harmful.  Is this one?  Maybe...
Fair point, although these tools are used differently;  compressing all
possible usages into one synopsis does lack information about which
options are mutually exclusive, but you can still available one which
is often what I'm looking for:

        ls [-1AaCcdFfgHhikLlmnopqRrSsTtux] [file ...]


Same goes for ldomctl (and vmctl), except doing something like

        ldomctl start|stop|init-system|... [domain|file|...]

is hardly possible or even useful.

Reply | Threaded
Open this post in threaded view
|

Re: ldomctl: improve usage

Klemens Nanni-2
In reply to this post by Theo de Raadt-2
On Sat, Jun 22, 2019 at 11:20:10AM -0600, Theo de Raadt wrote:
> The problem is when I'm on screens that don't have scroll-back, those 9
> lines have scrolled other information off the top, and then I've had to
> repeat the operations, or if not possible, been more frustrated.
Should we change those programs and refer to manual page or show a
synopsis one-liner instead?

I get the scroll-back argument, but I dare say it's a weak one given
that this is something users can fix most of the time, e.g. by using
tmux.

I'd really like to have a valuable usage in ldomctl and haven't come up
with a better and still consistent way of doing so.

ssh-keygen is another good example of long usage that is most probably
not going to change back to a simpler one;  I just stumbled over it due
to wrong usage and was therefore reminded of this mail thread.

What do other (ldomctl) users say?

Reply | Threaded
Open this post in threaded view
|

Re: ldomctl: improve usage

Andrew Grillet
As an ldomctl user, I would be happy for usage to be reasonably terse,
provided help gives a fuller description
- provided the usage mentions the help option.

If your screen does not have scroll back, the solution is a screen program
that does. It is not 1978 any more.

(Incidentally, do others have a very bad experience with the default
terminal when using Sparc[64]
consoles? Would the default of TERM=ansi help? Or is there a better
solution?)

On Sun, 30 Jun 2019 at 12:20, Klemens Nanni <[hidden email]> wrote:

> On Sat, Jun 22, 2019 at 11:20:10AM -0600, Theo de Raadt wrote:
> > The problem is when I'm on screens that don't have scroll-back, those 9
> > lines have scrolled other information off the top, and then I've had to
> > repeat the operations, or if not possible, been more frustrated.
> Should we change those programs and refer to manual page or show a
> synopsis one-liner instead?
>
> I get the scroll-back argument, but I dare say it's a weak one given
> that this is something users can fix most of the time, e.g. by using
> tmux.
>
> I'd really like to have a valuable usage in ldomctl and haven't come up
> with a better and still consistent way of doing so.
>
> ssh-keygen is another good example of long usage that is most probably
> not going to change back to a simpler one;  I just stumbled over it due
> to wrong usage and was therefore reminded of this mail thread.
>
> What do other (ldomctl) users say?
>
>
Reply | Threaded
Open this post in threaded view
|

Re: ldomctl: improve usage

Ingo Schwarze
In reply to this post by Klemens Nanni-2
Hi Klemens,

Klemens Nanni wrote on Sun, Jun 30, 2019 at 01:04:17PM +0200:
> On Sat, Jun 22, 2019 at 11:20:10AM -0600, Theo de Raadt wrote:

>> The problem is when I'm on screens that don't have scroll-back, those 9
>> lines have scrolled other information off the top, and then I've had to
>> repeat the operations, or if not possible, been more frustrated.

> Should we change those programs and refer to manual page or show a
> synopsis one-liner instead?

Yes, i think programs emitting excessive amounts of text (when called
with a typo, and even more so when doing that always on startup,
like gdb(1)) should be fixed to shut the hell up.  This is Unix.

> I get the scroll-back argument, but I dare say it's a weak one given
> that this is something users can fix most of the time, e.g. by using
> tmux.

I find it offensive being told to use tmux(1) merely because some
programs like to chew my ears off.  I get it that many developers
find tmux(1) useful for many purposes, but the availability of
add-on tools allowing workarounds is no excuse for programs being
annoying in my face.

Also, with tmux(1), i might get scrollback.  But having the immediate
command history remain on screen is still much better than being
able to scroll around and having to look for the relevant lines
buried among long, irrelevant output.

Yes, long usage is mostly irrelvant: a typo doesn't mean i need
to re-read a long list of commands provided.

> I'd really like to have a valuable usage in ldomctl and haven't
> come up with a better and still consistent way of doing so.

There is consensus two parts of documentation are useful:

 * A short usage message shown after typos,
   typically one or two lines.
 * The manual page, containing complete and concise
   reference documentation.

Personally, i wouldn't object to exceptionally complicated programs
(like openrsync(1) or ldomctl(1)) providing command summaries
(typically one line per command) *when the user explicitly asks for
it* with an option like -h or --help.

But i do see Theo's argument that likely we don't really need
three different levels of detail, adding additional maintenance
effort and danger of getting outdated.

> ssh-keygen is another good example of long usage that is most probably
> not going to change back to a simpler one;  I just stumbled over it due
> to wrong usage and was therefore reminded of this mail thread.
>
> What do other (ldomctl) users say?

This isn't really a question for ldomctl users at this point.

Usage should be very short as a matter consistency of the operating
system; in that sense, i do consider ssh-keygen(1) an offender.

*If* we decide that it would be valuable for selected programs to
provide an intermediate -h or --help, only then would it become
a question for ldomctl users whether ldomctl(8) is one of them.

But so far, i don't see consensus that we want to allow adding
such -h or --help options to base programs.  I'm mildly in favour
if in favour at all, and i have heard strong opposition, with
the reasonable argument that it adds maintenance effort for
little gain because it's not really that hard to find the
information quickly in a real manual page.

Yours,
  Ingo

Reply | Threaded
Open this post in threaded view
|

Re: ldomctl: improve usage

Klemens Nanni-2
Thanks for the input;  I won't persue such verbose usages any longer.

Another attempt was to continue grouping the commands by their arguments:

        $ ldomctl -h
        usage: ldomctl command [argument ...]
                ldomctl delete|select configuration
                ldomctl download directory
                ldomctl dump
                ldomctl list
                ldomctl init-system file
                ldomctl panic|start|status|stop [domain]

But this still seems long enough and even harder to read, so the
following patch simply cuts it to the synopsis as per the manual:

        $ ldomctl -h
        usage: ldomctl command [argument ...]

It contains less information than before, but is actually consistent
and not incomplete any longer, which bothers me with the current usage.

Feedback? Obections? OK?

Index: ldomctl.c
===================================================================
RCS file: /cvs/src/usr.sbin/ldomctl/ldomctl.c,v
retrieving revision 1.21
diff -u -p -r1.21 ldomctl.c
--- ldomctl.c 15 Sep 2018 13:20:16 -0000 1.21
+++ ldomctl.c 1 Jul 2019 19:45:59 -0000
@@ -157,10 +157,7 @@ main(int argc, char **argv)
 void
 usage(void)
 {
- extern char *__progname;
-
- fprintf(stderr, "usage: %s start|stop|panic domain\n", __progname);
- fprintf(stderr, "       %s status [domain]\n", __progname);
+ fprintf(stderr, "usage: %s command [argument ...]\n", getprogname());
  exit(EXIT_FAILURE);
 }
 

Reply | Threaded
Open this post in threaded view
|

Re: ldomctl: improve usage

Andrew Grillet
I assumed "usage" is printed in response to a failure to give the correct
combination of command and argument
and that -h (or help) would give more detail.
I would like the usage (response to incorrect combination) to be the
"synopsis" while the grouped commands and
their valid arguments is supplied for -h.
Reason being failure to give the correct format is most likely a typo
anyway, while, if an infrequent user, you
might need to check (eg) that download takes a directory, while init-system
takes a file and dump takes nothing.
(I can never remember whether it is init-system or system-init, as I do it
about once a year).
For anything more complex, there is "man".
Would two columns be a solution for those who struggle with scroll back?



On Tue, 2 Jul 2019 at 21:23, Klemens Nanni <[hidden email]> wrote:

> Thanks for the input;  I won't persue such verbose usages any longer.
>
> Another attempt was to continue grouping the commands by their arguments:
>
>         $ ldomctl -h
>         usage:  ldomctl command [argument ...]
>                 ldomctl delete|select configuration
>                 ldomctl download directory
>                 ldomctl dump
>                 ldomctl list
>                 ldomctl init-system file
>                 ldomctl panic|start|status|stop [domain]
>
> But this still seems long enough and even harder to read, so the
> following patch simply cuts it to the synopsis as per the manual:
>
>         $ ldomctl -h
>         usage: ldomctl command [argument ...]
>
> It contains less information than before, but is actually consistent
> and not incomplete any longer, which bothers me with the current usage.
>
> Feedback? Obections? OK?
>
> Index: ldomctl.c
> ===================================================================
> RCS file: /cvs/src/usr.sbin/ldomctl/ldomctl.c,v
> retrieving revision 1.21
> diff -u -p -r1.21 ldomctl.c
> --- ldomctl.c   15 Sep 2018 13:20:16 -0000      1.21
> +++ ldomctl.c   1 Jul 2019 19:45:59 -0000
> @@ -157,10 +157,7 @@ main(int argc, char **argv)
>  void
>  usage(void)
>  {
> -       extern char *__progname;
> -
> -       fprintf(stderr, "usage: %s start|stop|panic domain\n", __progname);
> -       fprintf(stderr, "       %s status [domain]\n", __progname);
> +       fprintf(stderr, "usage: %s command [argument ...]\n",
> getprogname());
>         exit(EXIT_FAILURE);
>  }
>
>
>
Reply | Threaded
Open this post in threaded view
|

Re: ldomctl: improve usage

Theo de Raadt-2
Andrew Grillet <[hidden email]> wrote:

> I assumed "usage" is printed in response to a failure to give the correct
> combination of command and argument
> and that -h (or help) would give more detail.

well you assumed wrong --- I don't believe we have a single utility in
the tree which behaves that way.  The usage messages are supposed to
remain constant, and one implication of that is to be concise.