avoid some overlong lines from posix urls, etc.

[gnulib.git] / doc / getdate.texi

diff --git a/doc/getdate.texi b/doc/getdate.texi
index 9280c50..48e8b68 100644 (file)
--- a/doc/getdate.texi
+++ b/doc/getdate.texi
@@ -1,10 +1,10 @@
 @c GNU date syntax documentation
 
 @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 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
 @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}
 @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
 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{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
 
 @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
 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.
 $ 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.
 
 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
 
 @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
 @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}
 
 @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
 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
 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.
 
 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.
 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
 
 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.
 
 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}.
 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}.