On Thu, Jul 04, 2024 at 12:01:55AM +0100, Jason McIntyre wrote:
> On Wed, Jul 03, 2024 at 10:08:09PM +0100, Stuart Henderson wrote:
> > >
> > > A random value (within the legal range) may be obtained by using the
> > > ???~???
> > > character in a field. The interval of the random value may be
> > > specified
> > > explicitly, for example ???0~30??? will result in a random value
> > > between 0
> > > and 30 inclusive. If either (or both) of the numbers on either side
> > > of
> > > the ???~??? are omitted, the appropriate limit (low or high) for the
> > > field
> > > will be used. The '~' character gets expanded to a random value
> > > only once, at table install time.
> >
> > "only once, at table install time" doesn't seem quite clear to me.
> > In particular consider "only once" when you edit the crontab once,
> > then edit it again.
> >
> > How about this?
> >
> > The '~' character gets expanded to a random value when the
> > .Nm crontab
> > is loaded.
> >
>
> well, we already say "A random value ... may be obtained", which i
> think is equivalent (note the singular). and this text does not
> explicitly say that it remains at this value afterwards, which is what
> we are supposed to be addressing.
>
> i still don;t think the complexity of the text is warranted. it works
> how it works. will someone stop using "random" because of this, or
> somehow be caught out (genuinely asking)?
>
> i'm not trying to reject the suggestion. i just think that being
> explicit will add a level of complexity that won;t be an improvement. i
> did try to rework the text! for example:
>
> A random, fixed, value...
>
> it's still not explicit ;(
>
> Once loaded, this value remains constant.
>
> don;t know...
>
> jmc
>
> > "The allowed values for the fields" above misses the various
> > possibilities involving ~ too.
> >
so a diff to try and address sthen and deraadt's points. i've tried to
be more explicit about the random value.
...
Fields are separated by blanks or tabs. The command may be one or more
fields long. The allowed values for the fields are:
field allowed values
minute *, ~, or 0-59
hour *, ~, or 0-23
day-of-month *, ~, or 1-31
month *, ~, 1-12, or a name (see below)
day-of-week *, ~, 0-7, or a name (0 or 7 is Sunday)
user a valid username
[flags] runtime flags, denoted with '-'
command text
...
A random value for a field may be obtained using the `~' character. A
value is generated every time the tab is loaded. On its own, it denotes
a random value appropriate for the field. It can also be used in a range
to make the interval more specific. If either of the numbers in a range
are omitted, the appropriate limit (low or high) for that field will be
used. For example, both "0~30" and "~30" in the minute field would
result in a random value between 0 and 30.
Index: crontab.5
===================================================================
RCS file: /cvs/src/usr.sbin/cron/crontab.5,v
diff -u -p -r1.42 crontab.5
--- crontab.5 6 May 2023 23:06:27 -0000 1.42
+++ crontab.5 4 Jul 2024 16:55:56 -0000
@@ -122,11 +122,11 @@ The command may be one or more fields lo
The allowed values for the fields are:
.Bl -column "day-of-month" "allowed values" -offset indent
.It Sy field Ta Sy allowed values
-.It Ar minute Ta * or 0\(en59
-.It Ar hour Ta * or 0\(en23
-.It Ar day-of-month Ta * or 1\(en31
-.It Ar month Ta * or 1\(en12 or a name (see below)
-.It Ar day-of-week Ta * or 0\(en7 or a name (0 or 7 is Sunday)
+.It Ar minute Ta *, ~, or 0\(en59
+.It Ar hour Ta *, ~, or 0\(en23
+.It Ar day-of-month Ta *, ~, or 1\(en31
+.It Ar month Ta *, ~, 1\(en12, or a name (see below)
+.It Ar day-of-week Ta *, ~, 0\(en7, or a name (0 or 7 is Sunday)
.It Ar user Ta a valid username
.It Op Ar flags Ta runtime flags, denoted with '-'
.It Ar command Ta text
@@ -147,15 +147,22 @@ For example,
.Ar hour
entry specifies execution at hours 8, 9, 10 and 11.
.Pp
-A random value (within the legal range) may be obtained by using the
+A random value for a field may be obtained using the
.Ql ~
-character in a field.
-The interval of the random value may be specified explicitly, for example
+character.
+A value is generated every time the tab is loaded.
+On its own,
+it denotes a random value appropriate for the field.
+It can also be used in a range to make the interval more specific.
+If either of the numbers in a range are omitted,
+the appropriate limit (low or high) for that field will be used.
+For example, both
.Dq 0~30
-will result in a random value between 0 and 30 inclusive.
-If either (or both) of the numbers on either side of the
-.Ql ~
-are omitted, the appropriate limit (low or high) for the field will be used.
+and
+.Dq ~30
+in the
+.Ar minute
+field would result in a random value between 0 and 30.
.Pp
Step values can be used in conjunction with ranges.
Following a range with
