1 files changed, 65 insertions, 5 deletions
diff --git a/doc/clock.n b/doc/clock.n
index e1253aa..5a6e3e4 100644
--- a/doc/clock.n
+++ b/doc/clock.n
@@ -101,6 +101,15 @@ slowing its clock by a tiny fraction for some minutes until it is
 back in sync with UTC; its data model does not represent minutes that
 have 59 or 61 seconds.
 .TP
+\fI\-now\fR
+Instead of \fItimeVal\fR a non-integer option \fI\-now\fR can be used as
+replacement for today, which is simply interpolated to the runt-time as value
+of \fBclock seconds\fR. For example:
+.sp
+\fBclock format -now -f %a; # current day of the week\fR
+.sp
+\fBclock add -now 1 month; # next month\fR
+.TP
 \fIunit\fR
 .
 One of the words, \fBseconds\fR, \fBminutes\fR, \fBhours\fR,
@@ -413,8 +422,12 @@ preprocessed format string.  In order of preference:
 If the string contains a \fB%s\fR format group, representing
 seconds from the epoch, that group is used to determine the date.
 .IP [2]
-If the string contains a \fB%J\fR format group, representing
-the Julian Day Number, that group is used to determine the date.
+If the string contains a \fB%J\fR, \fB%EJ\fR or \fB%Ej\fR format groups,
+representing the Calendar or Astronomical Julian Day Number, that groups
+are used to determine the date.
+Note, that in case of \fB%EJ\fR or \fB%Ej\fR format groups, representing
+the Julian Date with time fraction, this groups may be used to determine
+the date and time.
 .IP [3]
 If the string contains a complete set of format groups specifying
 century, year, month, and day of month; century, year, and day of year;
@@ -552,6 +565,33 @@ the string \fBB.C.E.\fR, \fBB.C.\fR, \fBC.E.\fR, \fBA.D.\fR, or the
 abbreviation appropriate to the current locale, and uses it to fix
 whether \fB%Y\fR refers to years before or after Year 1 of the
 Common Era.
+.IP \fB%Ej\fR
+On output, produces a string of digits giving the Astronomical Julian Date or
+Astronomical Julian Day Number (JDN/JD). In opposite to calendar julian day
+\fB%J\fR, it starts the day at noon.
+On input, accepts a string of digits (or floating point with the time fraction)
+and interprets it as an Astronomical Julian Day Number (JDN/JD).
+The Astronomical Julian Date is a count of the number of calendar days
+that have elapsed since 1 January, 4713 BCE of the proleptic
+Julian calendar, which contains also the time fraktion (after floating point).
+The epoch time of 1 January 1970 corresponds to Astronomical JDN 2440587.5.
+This value corresponds the julian day used in sqlite-database, and is the same
+as result of \fBselect julianday(:seconds, 'unixepoch')\fR.
+.IP \fB%EJ\fR
+On output, produces a string of digits giving the Calendar Julian Date.
+In opposite to julian day \fB%J\fR format group, it produces float number.
+In opposite to astronomical julian day \fB%Ej\fR group, it starts at midnight.
+On input, accepts a string of digits (or floating point with the time fraction)
+and interprets it as a Calendar Julian Day Number.
+The Calendar Julian Date is a count of the number of calendar days
+that have elapsed since 1 January, 4713 BCE of the proleptic
+Julian calendar, which contains also the time fraktion (after floating point).
+The epoch time of 1 January 1970 corresponds to Astronomical JDN 2440588.
+.IP \fB%Es\fR
+This affects similar to \fB%s\fR, but in opposition to \fB%s\fR it parses
+or formats local seconds (not the posix seconds).
+Because \fB%s\fR has the same precedence as \fB%s\fR (uniquely determines
+a point in time), it overrides all other input formats.
 .IP \fB%Ex\fR
 On output, produces a locale-dependent representation of the date
 in the locale's alternative calendar.  On input, matches
@@ -591,7 +631,7 @@ On output, produces a two-digit number giving the hour of the day
 On output, produces a three-digit number giving the day of the year
 (001-366).  On input, accepts such a number.
 .IP \fB%J\fR
-On output, produces a string of digits giving the Julian Day Number.
+On output, produces a string of digits giving the calendar Julian Day Number.
 On input, accepts a string of digits and interprets it as a Julian Day Number.
 The Julian Day Number is a count of the number of calendar days
 that have elapsed since 1 January, 4713 BCE of the proleptic
@@ -712,12 +752,14 @@ week number \fB%V\fR; programs should use \fB%G\fR for that purpose.
 On output, produces the current time zone, expressed in hours and
 minutes east (+hhmm) or west (\-hhmm) of Greenwich. On input, accepts a
 time zone specifier (see \fBTIME ZONES\fR below) that will be used to
-determine the time zone.
+determine the time zone (this token is optionally applicable on input,
+so the value is not mandatory and can be missing in input).
 .IP \fB%Z\fR
 On output, produces the current time zone's name, possibly
 translated to the given locale. On input, accepts a time zone
 specifier (see \fBTIME ZONES\fR below) that will be used to determine the
-time zone. This option should, in general, be used on input only when
+time zone (token is also like \fB%z\fR optionally applicable on input).
+This option should, in general, be used on input only when
 parsing RFC822 dates. Other uses are fraught with ambiguity; for
 instance, the string \fBBST\fR may represent British Summer Time or
 Brazilian Standard Time. It is recommended that date/time strings for
@@ -922,6 +964,24 @@ used.  Finally, a correction is applied so that the correct hour of
 the day is produced after allowing for daylight savings time
 differences and the correct date is given when going from the end
 of a long month to a short month.
+.PP
+The precedence of the applying of single tokens resp. which sequence will be
+used by calculating of the time is complex, e. g. heavily dependent on the
+precision of type of the token.
+.sp
+In example below the second date-string contains "next January", therefore
+it results in next year but in January. And third date-string besides "January"
+contains also additionally "Fri", so it results in the nearest Friday.
+Thus both win before "385 days" resp. make it more precise, because of higher
+precision of this token types.
+.CS
+% clock format [clock scan "5 years 18 months 385 days" -base 0 -gmt 1] -gmt 1
+Thu Jul 21 00:00:00 GMT 1977
+% clock format [clock scan "5 years 18 months 385 days next January" -base 0 -gmt 1] -gmt 1
+Sat Jan 21 00:00:00 GMT 1978
+% clock format [clock scan "5 years 18 months 385 days next January Fri" -base 0 -gmt 1] -gmt 1
+Fri Jan 27 00:00:00 GMT 1978
+.CE
 .SH "SEE ALSO"
 msgcat(n)
 .SH KEYWORDS