On Thu, Sep 02, 2021 at 05:47:09PM +0200, Leon Fischer wrote:
> > > @@ -34,83 +35,74 @@
> > > .Nd run a command with a time limit
> > > .Sh SYNOPSIS
> > > .Nm
> > > -.Op Fl Fl signal Ar sig | Fl s Ar sig
> > > -.Op Fl Fl preserve-status
> > > -.Op Fl Fl kill-after Ar time | Fl k Ar time
> > > -.Op Fl Fl foreground
> > > -.Ao Ar duration Ac
> > > -.Ao Ar command Ac
> > > -.Ao Ar args ... Ac
> > > +.Op Fl k Ar time
> > > +.Op Fl s Ar sig
> > > +.Op Fl -foreground
> > > +.Op Fl -preserve-status
> > > +.Ar duration
> > > +.Ar command
> > > +.Op Ar args
> >
> > why do you want to remove the long options from the synopsis?
>
> I copied this practice from sort(1), patch(1), less(1) and openrsync(1).
>
ooh, good spot.
> >
> > i do agree that it currently looks awful, but i think it's because of
> > how it's implemented: it has four flags, and two of them have no short
> > option equivalents. ouch! that does make it hard to propose a tidy
> > synopsis.
> >
> > still, i'm not sure axing the long options makes sense. it just make it
> > look like it's better implemented!
>
> Does it make sense to include redundant information in a summary?
>
> >
> > i thought about seperating them, like we do with grep. i.e. list -ks
> > seperately, then again as long options. that's horrible too.
>
> grep(1) is inconsistent with the other man pages I mentioned and one of
> the two sides should probably be changed to conform with the other.
>
> >
> > having said all that, i guess i'm not totally against obscuring the fact
> > that -k and -s have long options. but i suspect other people will, and
> > that we'll get mails telling us we forgot to list the long options in
> > synopsis.
>
> No mails so far for sort(1) and patch(1), which have been around
> forever.
>
given your points and theo's, i'm ok with this then, i guess.
> >
> > > .Sh DESCRIPTION
> > > +The
> > > .Nm
> > > -starts the
> > > -.Ar command
> > > -with its
> > > -.Ar args .
> > > -If
> > > -.Ar command
> > > -is still running after
> > > +utility executes the given command.
> > > +If it is still running after
> > > .Ar duration ,
> > > it is killed.
> >
> > this is ok, but you probably want to mark up "command"
>
> I took inspiration from the doas(1) man page, which only marks up
> "command" when referring to it as an argument. timeout(1) looked
> strange before with every paragraph containing a marked up "command".
>
yes, fair point. i also dislike excess markup. but i think in the first
sentence it is not excess, it is explanation. i mean "duration"is marked
up.
so that first sentence should try to talk about all those arg elements,
and mark each of them up. later, you can try and avoid being excessive.
The
.Nm
utility executes
.Ar command ,
with any
.Ar args ,
and kills it if it is still running after the specified
.Ar duration .
sth like that?
but i agree that you don;t want to keep continually marking it up.
> > > +.Pp
> > > +The options are as follows:
> > > +.Bl -tag -width Ds
> > > +.It Fl k Ar time , Fl -kill-after Ns = Ns Ar time
> > > +Send a second kill signal if the command is still running after
> > > .Ar time
> > > -after the first signal was sent.
> > > +after the first signal is sent.
> >
> > "after time after". ouch. (i know it's not your phrasing)
> >
> > how about
> >
> > ...still running
> > .Ar time
> > seconds after
>
> The problem is "time" doesn't have to be seconds; it can be "30m",
> "7d", etc. The GNU man page says "still running after this long" but I
> think it should mention the argument.
>
> Changed to "still running time after the first signal".
>
fine. i think it's good to write the text from the "what happens by
default" viewpoint, and exceptions are described in the relevant places.
so we should talk about duration as if it is in seconds - because it is
unless you say otherwise, in which case you know what you are doing.
you could refer to "timeout" as a period, i suppose.
>
> >
> > also i'm trying to understand what it means that the number can be a
> > "positive integer or real (decimal) number". what does this mean? it can
> > be n or n.n?
>
> Yes. I copied the phrasing from the FreeBSD man page.
>
> >
> > i think it'd be helpful to say upfront plainly what a valid timeout
> > would be, and that it's in seconds, and then later talk about adding
> > suffixes.
>
> Changed to "duration and time may contain a decimal fraction. The value
> defaults to seconds unless an unit-specifying suffix is given."
>
"unit-specifying suffix" does not sound great. maybe just "a specific
suffix" or "a time suffix"? or make your text match and use "unless a
unit symbol is given", or change the unit symbol text to match whatever
you use. then people will join dots.
>
> >
> > > -.It s
> > > +.It Cm s
> > > seconds
> > > -.It m
> > > +.It Cm m
> > > minutes
> > > -.It h
> > > +.It Cm h
> > > hours
> > > -.It d
> > > +.It Cm d
> > > days
>
> On second thought, simple list items aren't usually marked up.
>
they often are. i don;t object to not marking it up though.
> > > .El
> > > .Sh EXIT STATUS
> > > -If the timeout was not reached, the exit status of
> > > +If the timeout is not reached, the exit status of
> > > .Ar command
> > > is returned.
> >
> > in my opinion, the text read better using past tense. i don;t like these
> > changes.
>
> Most utility man pages say "The XYZ utility exits 0 on success, and >0
> if an error _occurs_". rm(1) for example says "The rm utility exits 0
> if all of the named files or file hierarchies _were_ removed".
>
> Tenses seem to be wildly inconsistent across different man pages, but
> I'll honor your request and word it more like rm(1): Present tense
> normally and past tense when talking about prerequisite or subsequent
> actions, e.g. "It _does_ this if this _was_ done".
>
tenses are not inconsistent. there are just multiple valid ways to say
the same thing. in this case i think my suggestion reads better, but
it's just my opinion.
jmc
>
> Index: timeout.1
> ===================================================================
> RCS file: /cvs/src/usr.bin/timeout/timeout.1,v
> retrieving revision 1.1
> diff -u -p -r1.1 timeout.1
> --- timeout.1 1 Sep 2021 15:50:33 -0000 1.1
> +++ timeout.1 2 Sep 2021 15:38:12 -0000
> @@ -1,3 +1,4 @@
> +.\" $OpenBSD$
> .\" $NetBSD: timeout.1,v 1.4 2016/10/13 06:22:26 dholland Exp $
> .\"
> .\" Copyright (c) 2014 Baptiste Daroussin <b...@freebsd.org>
> @@ -26,7 +27,7 @@
> .\"
> .\" $FreeBSD: head/usr.bin/timeout/timeout.1 268861 2014-07-18 22:56:59Z
> bapt $
> .\"
> -.Dd July 19, 2014
> +.Dd $Mdocdate$
> .Dt TIMEOUT 1
> .Os
> .Sh NAME
> @@ -34,57 +35,50 @@
> .Nd run a command with a time limit
> .Sh SYNOPSIS
> .Nm
> -.Op Fl Fl signal Ar sig | Fl s Ar sig
> -.Op Fl Fl preserve-status
> -.Op Fl Fl kill-after Ar time | Fl k Ar time
> -.Op Fl Fl foreground
> -.Ao Ar duration Ac
> -.Ao Ar command Ac
> -.Ao Ar args ... Ac
> +.Op Fl k Ar time
> +.Op Fl s Ar sig
> +.Op Fl -foreground
> +.Op Fl -preserve-status
> +.Ar duration
> +.Ar command
> +.Op Ar args
> .Sh DESCRIPTION
> +The
> .Nm
> -starts the
> -.Ar command
> -with its
> -.Ar args .
> -If
> -.Ar command
> -is still running after
> +utility executes the given command.
> +If it is still running after
> .Ar duration ,
> it is killed.
> -By default,
> -.Dv SIGTERM
> -is sent.
> -.Bl -tag -width "-k time, --kill-after time"
> -.It Fl Fl preserve-status
> -Always exits with the same status as
> -.Ar command
> -even if it times out.
> -.It Fl Fl foreground
> -Do not propagate timeout to the
> -.Ar command
> -children.
> -.It Fl s Ar sig , Fl Fl signal Ar sig
> -Specify the signal to send on timeout.
> -By default,
> -.Dv SIGTERM
> -is sent.
> -.It Fl k Ar time , Fl Fl kill-after Ar time
> -Send a second kill signal if
> -.Ar command
> -is still running after
> +If
> +.Ar duration
> +is 0, the timeout is disabled.
> +.Pp
> +The options are as follows:
> +.Bl -tag -width Ds
> +.It Fl k Ar time , Fl -kill-after Ns = Ns Ar time
> +Send a second kill signal if the command is still running
> .Ar time
> after the first signal was sent.
> +.It Fl s Ar sig , Fl -signal Ns = Ns Ar sig
> +Specify the signal to send on timeout, instead of the default
> +.Dv SIGTERM .
> +.It Fl -foreground
> +Do not propagate the timeout signal to children processes.
> +.It Fl -preserve-status
> +Always exit with the same status as
> +.Ar command
> +even if the timeout was reached.
> .El
> .Sh DURATION FORMAT
> .Ar duration
> and
> .Ar time
> -can be integer or decimal numbers.
> -Values without unit symbols are interpreted as seconds.
> +may contain a decimal fraction.
> +The value defaults to seconds unless an unit-specifying suffix is given.
> +.Pp
> +The supported unit symbols are:
> .Pp
> -Supported unit symbols are:
> -.Bl -tag -width indent -compact
> +.Bl -tag -width Ds -offset indent -compact
> .It s
> seconds
> .It m
> @@ -100,17 +94,18 @@ If the timeout was not reached, the exit
> is returned.
> .Pp
> If the timeout was reached and
> -.Fl Fl preserve-status
> -is set, the exit status of
> +.Fl -preserve-status
> +was set, the exit status of
> .Ar command
> is returned.
> If
> -.Fl Fl preserve-status
> -is not set, an exit status of 124 is returned.
> +.Fl -preserve-status
> +was not set, an exit status of 124 is returned.
> .Pp
> If
> .Ar command
> -exits after receiving a signal, the exit status returned is the signal
> number plus 128.
> +exited after receiving a signal, the exit status returned is the signal
> number
> +plus 128.
> .Sh SEE ALSO
> .Xr kill 1 ,
> .Xr signal 3
> Index: timeout.c
> ===================================================================
> RCS file: /cvs/src/usr.bin/timeout/timeout.c,v
> retrieving revision 1.17
> diff -u -p -r1.17 timeout.c
> --- timeout.c 2 Sep 2021 11:26:54 -0000 1.17
> +++ timeout.c 2 Sep 2021 15:38:12 -0000
> @@ -53,8 +53,10 @@ static sig_atomic_t sig_ign = 0;
> static void __dead
> usage(void)
> {
> - fprintf(stderr, "usage: timeout [-s sig] [-k time] [--preserve-status]"
> - " [--foreground] duration command\n");
> + fprintf(stderr,
> + "usage: timeout [-k time] [-s sig] [--foreground]"
> + " [--preserve-status] duration\n"
> + " command [args]\n");
>
> exit(1);
> }
