X-Git-Url: https://git.gag.com/?a=blobdiff_plain;f=doc%2Fparse-datetime.texi;h=6b3e973e8b6716f27f9d66ad015cbab1647165f2;hb=daa269958ad8d50ef8154ccb65e58acaf7a6dd99;hp=2f1ab34ec5ec7a6e2eaef98415ea4850a3a45aec;hpb=1a44d77d50f4fb37c0410eed04b82303624ea2ec;p=debian%2Ftar

diff --git a/doc/parse-datetime.texi b/doc/parse-datetime.texi
index 2f1ab34e..6b3e973e 100644
--- a/doc/parse-datetime.texi
+++ b/doc/parse-datetime.texi
@@ -1,6 +1,6 @@
 @c GNU date syntax documentation
 
-@c Copyright (C) 1994-2006, 2009-2011 Free Software Foundation, Inc.
+@c Copyright (C) 1994-2006, 2009-2013 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.3 or
@@ -38,10 +38,10 @@ demanded a knowledge of five different languages.  It is no wonder then
 that we often look into our own immediate past or future, last Tuesday
 or a week from Sunday, with feelings of helpless confusion.  @dots{}
 
---- Robert Grudin, @cite{Time and the Art of Living}.
+---Robert Grudin, @cite{Time and the Art of Living}.
 @end quotation
 
-This section describes the textual date representations that @sc{gnu}
+This section describes the textual date representations that GNU
 programs accept.  These are the strings you, as a user, can supply as
 arguments to the various programs.  The C interface (via the
 @code{parse_datetime} function) is not described here.
@@ -50,7 +50,8 @@ arguments to the various programs.  The C interface (via the
 * General date syntax::            Common rules.
 * Calendar date items::            19 Dec 1994.
 * Time of day items::              9:20pm.
-* Time zone items::                @sc{est}, @sc{pdt}, @sc{gmt}.
+* Time zone items::                EST, PDT, UTC, @dots{}
+* Combined date and time of day items:: 1972-09-24T20:02:00,000000-0500.
 * Day of week items::              Monday and others.
 * Relative items in date strings:: next tuesday, 2 years ago.
 * Pure numbers in date strings::   19931219, 1440.
@@ -76,6 +77,7 @@ many flavors of items:
 @item calendar date items
 @item time of day items
 @item time zone items
+@item combined date and time of day items
 @item day of the week items
 @item relative items
 @item pure numbers.
@@ -115,10 +117,10 @@ abbreviations like @samp{AM}, @samp{DST}, @samp{EST}, @samp{first},
 The output of the @command{date} command
 is not always acceptable as a date string,
 not only because of the language problem, but also because there is no
-standard meaning for time zone items like @samp{IST}.  When using
+standard meaning for time zone items like @samp{IST}@.  When using
 @command{date} to generate a date string intended to be parsed later,
 specify a date format that is independent of language and that does not
-use time zone items other than @samp{UTC} and @samp{Z}.  Here are some
+use time zone items other than @samp{UTC} and @samp{Z}@.  Here are some
 ways to do this:
 
 @example
@@ -126,8 +128,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 | tr T ' '  # --iso-8601 is a GNU extension.
-2004-02-29 16:21:42,692722128-0800
+$ date --rfc-3339=ns  # --rfc-3339 is a GNU extension.
+2004-02-29 16:21:42.692722128-08:00
 $ 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.
@@ -143,6 +145,7 @@ 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.
 
+@cindex leap seconds
 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
@@ -159,7 +162,7 @@ specified differently, depending on whether the month is specified
 numerically or literally.  All these strings specify the same calendar date:
 
 @example
-1972-09-24     # @sc{iso} 8601.
+1972-09-24     # ISO 8601.
 72-9-24        # Assume 19xx for 69 through 99,
                # 20xx for 00 through 68.
 72-09-24       # Leading zeros are ignored.
@@ -182,9 +185,9 @@ sep 24
 
 Here are the rules.
 
-@cindex @sc{iso} 8601 date format
-@cindex date format, @sc{iso} 8601
-For numeric months, the @sc{iso} 8601 format
+@cindex ISO 8601 date format
+@cindex date format, ISO 8601
+For numeric months, the ISO 8601 format
 @samp{@var{year}-@var{month}-@var{day}} is allowed, where @var{year} is
 any positive number, @var{month} is a number between 01 and 12, and
 @var{day} is a number between 01 and 31.  A leading zero must be present
@@ -232,9 +235,10 @@ day.  Here are some examples, all of which represent the same time:
 20:02:00.000000
 20:02
 8:02pm
-20:02-0500      # In @sc{est} (U.S. Eastern Standard Time).
+20:02-0500      # In EST (U.S. Eastern Standard Time).
 @end example
 
+@cindex leap seconds
 More generally, the time of day may be given as
 @samp{@var{hour}:@var{minute}:@var{second}}, where @var{hour} is
 a number between 0 and 23, @var{minute} is a number between 0 and
@@ -270,10 +274,10 @@ 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
+Coordinated Universal Time (UTC), overriding any previous
 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).
+ahead of 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.
@@ -311,6 +315,32 @@ time stamps are interpreted using the rules of the default time zone
 (@pxref{Specifying time zone rules}).
 
 
+@node Combined date and time of day items
+@section Combined date and time of day items
+
+@cindex combined date and time of day item
+@cindex ISO 8601 date and time of day format
+@cindex date and time of day format, ISO 8601
+
+The ISO 8601 date and time of day extended format consists of an ISO
+8601 date, a @samp{T} character separator, and an ISO 8601 time of
+day.  This format is also recognized if the @samp{T} is replaced by a
+space.
+
+In this format, the time of day should use 24-hour notation.
+Fractional seconds are allowed, with either comma or period preceding
+the fraction.  ISO 8601 fractional minutes and hours are not
+supported.  Typically, hosts support nanosecond timestamp resolution;
+excess precision is silently discarded.
+
+Here are some examples:
+
+@example
+2012-09-24T20:02:00.052-0500
+2012-12-31T23:59:59,999999999+1100
+1970-01-01 00:00Z
+@end example
+
 @node Day of week items
 @section Day of week items
 
@@ -455,28 +485,29 @@ supported by the internal representation is truncated toward minus
 infinity.  Such a number cannot be combined with any other date
 item, as it specifies a complete time stamp.
 
-@cindex beginning of time, for @acronym{POSIX}
-@cindex epoch, for @acronym{POSIX}
+@cindex beginning of time, for POSIX
+@cindex epoch, for POSIX
 Internally, computer times are represented as a count of seconds since
-an epoch---a well-defined point of time.  On @acronym{GNU} and
-@acronym{POSIX} systems, the epoch is 1970-01-01 00:00:00 @sc{utc}, so
+an epoch---a well-defined point of time.  On GNU and
+POSIX systems, the epoch is 1970-01-01 00:00:00 UTC, so
 @samp{@@0} represents this time, @samp{@@1} represents 1970-01-01
-00:00:01 @sc{utc}, and so forth.  @acronym{GNU} and most other
-@acronym{POSIX}-compliant systems support such times as an extension
-to @acronym{POSIX}, using negative counts, so that @samp{@@-1}
-represents 1969-12-31 23:59:59 @sc{utc}.
+00:00:01 UTC, and so forth.  GNU and most other
+POSIX-compliant systems support such times as an extension
+to POSIX, using negative counts, so that @samp{@@-1}
+represents 1969-12-31 23:59:59 UTC.
 
 Traditional Unix systems count seconds with 32-bit two's-complement
 integers and can represent times from 1901-12-13 20:45:52 through
-2038-01-19 03:14:07 @sc{utc}.  More modern systems use 64-bit counts
+2038-01-19 03:14:07 UTC@.  More modern systems use 64-bit counts
 of seconds with nanosecond subcounts, and can represent all the times
 in the known lifetime of the universe to a resolution of 1 nanosecond.
 
+@cindex leap seconds
 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 UTC, @samp{@@915148800} represents 1999-01-01 00:00:00
+UTC, and there is no way to represent the intervening leap second
+1998-12-31 23:59:60 UTC.
 
 @node Specifying time zone rules
 @section Specifying time zone rules
@@ -491,7 +522,7 @@ two quote characters (@samp{"}) must be present in the date, and any
 quotes or backslashes within @var{rule} must be escaped by a
 backslash.
 
-For example, with the @acronym{GNU} @command{date} command you can
+For example, with the GNU @command{date} command you can
 answer the question ``What time is it in New York when a Paris clock
 shows 6:30am on October 31, 2004?'' by using a date beginning with
 @samp{TZ="Europe/Paris"} as shown in the following shell transcript:
@@ -515,16 +546,16 @@ A @env{TZ} value is a rule that typically names a location in the
 @uref{http://www.twinsun.com/tz/tz-link.htm, @samp{tz} database}.
 A recent catalog of location names appears in the
 @uref{http://twiki.org/cgi-bin/xtra/tzdate, TWiki Date and Time
-Gateway}.  A few non-@acronym{GNU} hosts require a colon before a
+Gateway}.  A few non-GNU hosts require a colon before a
 location name in a @env{TZ} setting, e.g.,
 @samp{TZ=":America/New_York"}.
 
 The @samp{tz} database includes a wide variety of locations ranging
 from @samp{Arctic/Longyearbyen} to @samp{Antarctica/South_Pole}, but
 if you are at sea and have your own private time zone, or if you are
-using a non-@acronym{GNU} host that does not support the @samp{tz}
-database, you may need to use a @acronym{POSIX} rule instead.  Simple
-@acronym{POSIX} rules like @samp{UTC0} specify a time zone without
+using a non-GNU host that does not support the @samp{tz}
+database, you may need to use a POSIX rule instead.  Simple
+POSIX rules like @samp{UTC0} specify a time zone without
 daylight saving time; other rules can specify simple daylight saving
 regimes.  @xref{TZ Variable,, Specifying the Time Zone with @code{TZ},
 libc, The GNU C Library}.
@@ -548,7 +579,7 @@ implemented by Steven M. Bellovin
 at Chapel Hill.  The code was later tweaked by a couple of people on
 Usenet, then completely overhauled by Rich $alz (@email{rsalz@@bbn.com})
 and Jim Berets (@email{jberets@@bbn.com}) in August, 1990.  Various
-revisions for the @sc{gnu} system were made by David MacKenzie, Jim Meyering,
+revisions for the GNU system were made by David MacKenzie, Jim Meyering,
 Paul Eggert and others, including renaming it to @code{get_date} to
 avoid a conflict with the alternative Posix function @code{getdate},
 and a later rename to @code{parse_datetime}.  The Posix function
@@ -560,4 +591,4 @@ file, and lacks the thread-safety of @code{parse_datetime}.
 @cindex Berry, K.
 This chapter was originally produced by Fran@,{c}ois Pinard
 (@email{pinard@@iro.umontreal.ca}) from the @file{parse_datetime.y} source code,
-and then edited by K.@: Berry (@email{kb@@cs.umb.edu}).
+and then edited by K. Berry (@email{kb@@cs.umb.edu}).