X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;f=doc%2Fgetdate.texi;h=48e8b683433051a74458a90d729a7f953c643b25;hb=4f2ec69bf1dbf08065d2e248f4fcee2a52f52675;hp=9280c50877df016d7f761bb6221bae9e7d5fa8b5;hpb=c8041fc1d1b373da43e11b4048dd0ecc320a9955;p=gnulib.git

diff --git a/doc/getdate.texi b/doc/getdate.texi
index 9280c5087..48e8b6834 100644
--- a/doc/getdate.texi
+++ b/doc/getdate.texi
@@ -1,10 +1,10 @@
 @c GNU date syntax documentation
 
-@c Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
-@c 2003, 2004 Free Software Foundation, Inc.
+@c Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003,
+@c 2004, 2005, 2006, 2009, 2010 Free Software Foundation, Inc.
 
 @c Permission is granted to copy, distribute and/or modify this document
-@c under the terms of the GNU Free Documentation License, Version 1.1 or
+@c under the terms of the GNU Free Documentation License, Version 1.3 or
 @c any later version published by the Free Software Foundation; with no
 @c Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
 @c Texts.  A copy of the license is included in the ``GNU Free
@@ -89,13 +89,17 @@ many flavors of items:
 @findex first @r{in date strings}
 @findex next @r{in date strings}
 @findex last @r{in date strings}
-A few numbers may be written out in words in most contexts.  This is
+A few ordinal numbers may be written out in words in some contexts.  This is
 most useful for specifying day of the week items or relative items (see
-below).  Here is the list: @samp{first} for 1, @samp{next} for 2,
-@samp{third} for 3, @samp{fourth} for 4, @samp{fifth} for 5,
+below).  Among the most commonly used ordinal numbers, the word
+@samp{last} stands for @math{-1}, @samp{this} stands for 0, and
+@samp{first} and @samp{next} both stand for 1.  Because the word
+@samp{second} stands for the unit of time there is no way to write the
+ordinal number 2, but for convenience @samp{third} stands for 3,
+@samp{fourth} for 4, @samp{fifth} for 5,
 @samp{sixth} for 6, @samp{seventh} for 7, @samp{eighth} for 8,
 @samp{ninth} for 9, @samp{tenth} for 10, @samp{eleventh} for 11 and
-@samp{twelfth} for 12.  Also, @samp{last} means exactly @math{-1}.
+@samp{twelfth} for 12.
 
 @cindex months, written-out
 When a month is written this way, it is still considered to be written
@@ -123,8 +127,8 @@ $ LC_ALL=C TZ=UTC0 date
 Mon Mar  1 00:21:42 UTC 2004
 $ TZ=UTC0 date +'%Y-%m-%d %H:%M:%SZ'
 2004-03-01 00:21:42Z
-$ date --iso-8601=ns  # a GNU extension
-2004-02-29T16:21:42,692722128-0800
+$ date --iso-8601=ns | tr T ' '  # --iso-8601 is a GNU extension.
+2004-02-29 16:21:42,692722128-0800
 $ date --rfc-2822  # a GNU extension
 Sun, 29 Feb 2004 16:21:42 -0800
 $ date +'%Y-%m-%d %H:%M:%S %z'  # %z is a GNU extension.
@@ -140,6 +144,11 @@ between round parentheses, as long as included parentheses are properly
 nested.  Hyphens not followed by a digit are currently ignored.  Leading
 zeros on numbers are ignored.
 
+Invalid dates like @samp{2005-02-29} or times like @samp{24:00} are
+rejected.  In the typical case of a host that does not support leap
+seconds, a time like @samp{23:59:60} is rejected even if it
+corresponds to a valid leap second.
+
 
 @node Calendar date items
 @section Calendar date items
@@ -234,7 +243,8 @@ a number between 0 and 23, @var{minute} is a number between 0 and
 @samp{.} or @samp{,} and a fraction containing one or more digits.
 Alternatively,
 @samp{:@var{second}} can be omitted, in which case it is taken to
-be zero.
+be zero.  On the rare hosts that support leap seconds, @var{second}
+may be 60.
 
 @findex am @r{in date strings}
 @findex pm @r{in date strings}
@@ -255,13 +265,19 @@ which uses @samp{12m} for noon and @samp{12pm} for midnight.)
 The time may alternatively be followed by a time zone correction,
 expressed as @samp{@var{s}@var{hh}@var{mm}}, where @var{s} is @samp{+}
 or @samp{-}, @var{hh} is a number of zone hours and @var{mm} is a number
-of zone minutes.  When a time zone correction is given this way, it
+of zone minutes.
+The zone minutes term, @var{mm}, may be omitted, in which case
+the one- or two-digit correction is interpreted as a number of hours.
+You can also separate @var{hh} from @var{mm} with a colon.
+When a time zone correction is given this way, it
 forces interpretation of the time relative to
 Coordinated Universal Time (@sc{utc}), overriding any previous
-specification for the time zone or the local time zone.  The @var{minute}
-part of the time of day may not be elided when a time zone correction
-is used.  This is the best way to specify a time zone correction by
-fractional parts of an hour.
+specification for the time zone or the local time zone.  For example,
+@samp{+0530} and @samp{+05:30} both stand for the time zone 5.5 hours
+ahead of @sc{utc} (e.g., India).
+This is the best way to
+specify a time zone correction by fractional parts of an hour.
+The maximum zone correction is 24 hours.
 
 Either @samp{am}/@samp{pm} or a time zone correction may be specified,
 but not both.
@@ -279,6 +295,10 @@ Time.  Any included periods are ignored.  By following a
 non-daylight-saving time zone by the string @samp{DST} in a separate
 word (that is, separated by some white space), the corresponding
 daylight saving time zone may be specified.
+Alternatively, a non-daylight-saving time zone can be followed by a
+time zone correction, to add the two values.  This is normally done
+only for @samp{UTC}; for example, @samp{UTC+05:30} is equivalent to
+@samp{+05:30}.
 
 Time zone items other than @samp{UTC} and @samp{Z}
 are obsolescent and are not recommended, because they
@@ -453,8 +473,8 @@ integers and can represent times from 1901-12-13 20:45:52 through
 of seconds with nanosecond subcounts, and can represent all the times
 in the known lifetime of the universe to a resolution of 1 nanosecond.
 
-On most systems, these counts ignore the presence of leap seconds.
-For example, on most systems @samp{@@915148799} represents 1998-12-31
+On most hosts, these counts ignore the presence of leap seconds.
+For example, on most hosts @samp{@@915148799} represents 1998-12-31
 23:59:59 @sc{utc}, @samp{@@915148800} represents 1999-01-01 00:00:00
 @sc{utc}, and there is no way to represent the intervening leap second
 1998-12-31 23:59:60 @sc{utc}.