* doc/tests/clock.test: Added numerous tests for clock scan.

        * doc/generic/tclGetDate.y: Fixed some shift/reduce conflicts in
        clock grammar.

        * doc/doc/clock.n: Added documentation for new supported clock
        scan formats and additional explanation of daylight savings time
        correction algorithm.

1 files changed, 65 insertions, 193 deletions

diff --git a/doc/clock.n b/doc/clock.n
index ed3daa9..2075e96 100644
--- a/doc/clock.n
+++ b/doc/clock.n
@@ -1,193 +1,65 @@
-'\"
-'\" Copyright (c) 1992-1995 Karl Lehenbauer and Mark Diekhans.
-'\" Copyright (c) 1995-1997 Sun Microsystems, Inc.
-'\" Copyright (c) 1998-1999 Scriptics Corporation
-'\"
-'\" This documentation is derived from the time and date facilities of
-'\" TclX, by Mark Diekhans and Karl Lehenbauer.
-'\" 
-'\" See the file "license.terms" for information on usage and redistribution
-'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-'\" RCS: @(#) $Id: clock.n,v 1.4 1999/09/21 04:20:35 hobbs Exp $
-'\" 
-.so man.macros
-.TH clock n 8.3 Tcl "Tcl Built-In Commands"
-.BS
-'\" Note:  do not modify the .SH NAME line immediately below!
-.SH NAME
-clock \- Obtain and manipulate time
-.SH SYNOPSIS
-\fBclock \fIoption\fR ?\fIarg arg ...\fR?
-.BE
-
-.SH DESCRIPTION
-.PP
-This command performs one of several operations that may obtain
-or manipulate strings or values that represent some notion of
-time.  The \fIoption\fR argument determines what action is carried
-out by the command.  The legal \fIoptions\fR (which may be
-abbreviated) are:
-.TP
-.VS 8.3
-\fBclock clicks\fR ?\fB\-milliseconds\fR?
-Return a high-resolution time value as a system-dependent integer
-value.  The unit of the value is system-dependent but should be the
-highest resolution clock available on the system such as a CPU cycle
-counter. If \fB\-milliseconds\fR is specified, then the value is
-guaranteed to be of millisecond granularity.
-This value should only be used for the relative measurement
-of elapsed time.
-.VE 8.3
-.TP
-\fBclock format \fIclockValue\fR ?\fB\-format \fIstring\fR? ?\fB\-gmt \fIboolean\fR?
-Converts an integer time value, typically returned by
-\fBclock seconds\fR, \fBclock scan\fR, or the \fBatime\fR, \fBmtime\fR,
-or \fBctime\fR options of the \fBfile\fR command, to human-readable
-form.  If the \fB\-format\fR argument is present the next argument is a
-string that describes how the date and time are to be formatted.
-Field descriptors consist of a \fB%\fR followed by a field
-descriptor character.  All other characters are copied into the result.
-Valid field descriptors are:
-.RS
-.IP \fB%%\fR
-Insert a %.
-.IP \fB%a\fR
-Abbreviated weekday name (Mon, Tue, etc.).
-.IP \fB%A\fR
-Full weekday name (Monday, Tuesday, etc.).
-.IP \fB%b\fR
-Abbreviated month name (Jan, Feb, etc.).
-.IP \fB%B\fR
-Full month name.
-.IP \fB%c\fR
-Locale specific date and time.
-.IP \fB%d\fR
-Day of month (01 - 31).
-.IP \fB%H\fR
-Hour in 24-hour format (00 - 23).
-.IP \fB%I\fR
-Hour in 12-hour format (00 - 12).
-.IP \fB%j\fR
-Day of year (001 - 366).
-.IP \fB%m\fR
-Month number (01 - 12).
-.IP \fB%M\fR
-Minute (00 - 59).
-.IP \fB%p\fR
-AM/PM indicator.
-.IP \fB%S\fR
-Seconds (00 - 59).
-.IP \fB%U\fR
-Week of year (00 - 52), Sunday is the first day of the week.
-.IP \fB%w\fR
-Weekday number (Sunday = 0).
-.IP \fB%W\fR
-Week of year (00 - 52), Monday is the first day of the week.
-.IP \fB%x\fR
-Locale specific date format.
-.IP \fB%X\fR
-Locale specific time format.
-.IP \fB%y\fR
-Year without century (00 - 99).
-.IP \fB%Y\fR
-Year with century (e.g. 1990)
-.IP \fB%Z\fR
-Time zone name.
-.RE
-.sp
-.RS
-In addition, the following field descriptors may be supported on some
-systems (e.g. Unix but not Windows):
-.IP \fB%D\fR
-Date as %m/%d/%y.
-.IP \fB%e\fR
-Day of month (1 - 31), no leading zeros.
-.IP \fB%h\fR
-Abbreviated month name.
-.IP \fB%n\fR
-Insert a newline.
-.IP \fB%r\fR
-Time as %I:%M:%S %p.
-.IP \fB%R\fR
-Time as %H:%M.
-.IP \fB%t\fR
-Insert a tab.
-.IP \fB%T\fR
-Time as %H:%M:%S.
-.RE
-.sp
-.RS
-If the \fB\-format\fR argument is not specified, the format string 
-"\fB%a %b %d %H:%M:%S %Z %Y\fR" is used.  If the \fB\-gmt\fR argument
-is present the next argument must be a boolean which if true specifies
-that the time will be formatted as Greenwich Mean Time. If false
-then the local timezone will be used as defined by the operating
-environment.
-.RE
-.TP
-\fBclock scan \fIdateString\fR ?\fB\-base \fIclockVal\fR? ?\fB\-gmt \fIboolean\fR?
-Convert \fIdateString\fR to an integer clock value (see \fBclock seconds\fR).
-This command can parse and convert virtually any standard date and/or time
-string, which can include standard time zone mnemonics.  If only a time is
-specified, the current date is assumed.  If the string does not contain a
-time zone mnemonic, the local time zone is assumed, unless the \fB\-gmt\fR 
-argument is true, in which case the clock value is calculated assuming
-that the specified time is relative to Greenwich Mean Time.
-.sp
-If the \fB\-base\fR flag is specified, the next argument should contain
-an integer clock value.  Only the date in this value is used, not the
-time.  This is useful for determining the time on a specific day or
-doing other date-relative conversions.
-.sp
-The \fIdateString\fR consists of zero or more specifications of the
-following form:
-.RS
-.TP
-\fItime\fR
-A time of day, which is of the form: \fIhh\fR?\fI:mm\fR?\fI:ss\fR?? 
-?\fImeridian\fR? ?\fIzone\fR? or \fIhhmm \fR?\fImeridian\fR? 
-?\fIzone\fR?. If no meridian is specified, \fIhh\fR is interpreted on
-a 24-hour clock.
-.TP
-\fIdate\fR
-A specific month and day with optional year.  The
-acceptable formats are \fImm/dd\fR?\fI/yy\fR?, \fImonthname dd\fR
-?, \fIyy\fR?, \fIdd monthname \fR?\fIyy\fR? and \fIday, dd monthname
-yy\fR.  The default year is the current year.  If the year is less
-.VS
-than 100, we treat the years 00-68 as 2000-2068 and the years 69-99
-as 1969-1999.  Not all platforms can represent the years 38-70, so
-an error may result if these years are used.
-.VE
-.TP
-\fIrelative time\fR
-A specification relative to the current time.  The format is \fInumber
-unit\fR acceptable units are \fByear\fR, \fBfortnight\fR, \fBmonth\fR, \fBweek\fR, \fBday\fR,
-\fBhour\fR, \fBminute\fR (or \fBmin\fR), and \fBsecond\fR (or \fBsec\fR).  The
-unit can be specified as a singular or plural, as in \fB3 weeks\fR.
-These modifiers may also be specified:
-\fBtomorrow\fR, \fByesterday\fR, \fBtoday\fR, \fBnow\fR,
-\fBlast\fR, \fBthis\fR, \fBnext\fR, \fBago\fR.
-.RE
-.sp
-.RS
-The actual date is calculated according to the following steps.
-First, any absolute date and/or time is processed and converted.
-Using that time as the base, day-of-week specifications are added.
-Next, relative specifications are used.  If a date or day is
-specified, and no absolute or relative time is given, midnight is
-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.
-.RE
-.TP
-\fBclock seconds\fR
-Return the current date and time as a system-dependent integer value.  The
-unit of the value is seconds, allowing it to be used for relative time
-calculations.  The value is usually defined as total elapsed time from
-an ``epoch''.  You shouldn't assume the value of the epoch.
-
-.SH KEYWORDS
-clock, date, time
+PCL-CVS release R-2_0-Beta_2.  Copyright (C) 1991-1995 Per Cederqvist
+Pcl-cvs comes with absolutely no warranty; for details consult the manual.
+This is free software, and you are welcome to redistribute it under certain
+conditions; again, consult the Texinfo manual for details.
+
+In directory :
+         * Modified   ci          ChangeLog
+
+In directory compat/:
+
+In directory doc/:
+         * Modified   ci          doc/clock.n
+
+In directory generic/:
+           Unknown                generic/clock.lex
+           Unknown                generic/foo
+         * Modified   ci          generic/tclDate.c
+         * Modified   ci          generic/tclGetDate.y
+           Unknown                generic/y.tab.c
+
+In directory library/:
+
+In directory library/dde1.0/:
+
+In directory library/dde1.1/:
+
+In directory library/encoding/:
+
+In directory library/http1.0/:
+
+In directory library/http2.0/:
+
+In directory library/http2.1/:
+
+In directory library/msgcat1.0/:
+
+In directory library/opt0.1/:
+
+In directory library/opt0.4/:
+
+In directory library/reg1.0/:
+
+In directory library/tcltest1.0/:
+
+In directory mac/:
+
+In directory tests/:
+         * Modified   ci          tests/clock.test
+
+In directory tests/pkg/:
+
+In directory tests/pkg1/:
+
+In directory tools/:
+
+In directory tools/encoding/:
+
+In directory unix/:
+           Unknown                unix/sttNrknd
+           Unknown                unix/stuJRhh5
+
+In directory unix/dltest/:
+
+In directory win/:
+--------------------- End ---------------------