GNU Emacs @value{EMACSVER}.
@end ifnotinfo
-Copyright @copyright{} 1990-1991, 2001-2012 Free Software Foundation, Inc.
+Copyright @copyright{} 1990--1991, 2001--2013 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
entitled ``GNU Free Documentation License.''
(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
-modify this GNU manual. Buying copies from the FSF supports it in
-developing GNU and promoting software freedom.''
+modify this GNU manual.''
@end quotation
@end copying
functions, your date formats should avoid using the @samp{#} character.
@menu
+* ISO 8601::
* Date Formatting Codes::
* Free-Form Dates::
* Standard Date Formats::
@end menu
-@node Date Formatting Codes, Free-Form Dates, Date Formats, Date Formats
+@node ISO 8601, Date Formatting Codes, Date Formats, Date Formats
+@subsubsection ISO 8601
+
+@noindent
+@cindex ISO 8601
+The same date can be written down in different formats and Calc tries
+to allow you to choose your preferred format. Some common formats are
+ambiguous, however; for example, 10/11/2012 means October 11,
+2012 in the United States but it means November 10, 2012 in
+Europe. To help avoid such ambiguities, the International Organization
+for Standardization (ISO) provides the ISO 8601 standard, which
+provides three different but easily distinguishable and unambiguous
+ways to represent a date.
+
+The ISO 8601 calendar date representation is
+
+@example
+ @var{YYYY}-@var{MM}-@var{DD}
+@end example
+
+@noindent
+where @var{YYYY} is the four digit year, @var{MM} is the two-digit month
+number (01 for January to 12 for December), and @var{DD} is the
+two-digit day of the month (01 to 31). (Note that @var{YYYY} does not
+correspond to Calc's date formatting code, which will be introduced
+later.) The year, which should be padded with zeros to ensure it has at
+least four digits, is the Gregorian year, except that the year before
+0001 (1 AD) is the year 0000 (1 BC). The date October 11, 2012 is
+written 2012-10-11 in this representation and November 10, 2012 is
+written 2012-11-10.
+
+The ISO 8601 ordinal date representation is
+
+@example
+ @var{YYYY}-@var{DDD}
+@end example
+
+@noindent
+where @var{YYYY} is the year, as above, and @var{DDD} is the day of the year.
+The date December 31, 2011 is written 2011-365 in this representation
+and January 1, 2012 is written 2012-001.
+
+The ISO 8601 week date representation is
+
+@example
+ @var{YYYY}-W@var{ww}-@var{D}
+@end example
+
+@noindent
+where @var{YYYY} is the ISO week-numbering year, @var{ww} is the two
+digit week number (preceded by a literal ``W''), and @var{D} is the day
+of the week (1 for Monday through 7 for Sunday). The ISO week-numbering
+year is based on the Gregorian year but can differ slightly. The first
+week of an ISO week-numbering year is the week with the Gregorian year's
+first Thursday in it (equivalently, the week containing January 4);
+any day of that week (Monday through Sunday) is part of the same ISO
+week-numbering year, any day from the previous week is part of the
+previous year. For example, January 4, 2013 is on a Friday, and so
+the first week for the ISO week-numbering year 2013 starts on
+Monday, December 31, 2012. The day December 31, 2012 is then part of the
+Gregorian year 2012 but ISO week-numbering year 2013. In the week
+date representation, this week goes from 2013-W01-1 (December 31,
+2012) to 2013-W01-7 (January 6, 2013).
+
+All three ISO 8601 representations arrange the numbers from most
+significant to least significant; as well as being unambiguous
+representations, they are easy to sort since chronological order in
+this formats corresponds to lexicographical order. The hyphens are
+sometimes omitted.
+
+The ISO 8601 standard uses a 24 hour clock; a particular time is
+represented by @var{hh}:@var{mm}:@var{ss} where @var{hh} is the
+two-digit hour (from 00 to 24), @var{mm} is the two-digit minute (from
+00 to 59) and @var{ss} is the two-digit second. The seconds or minutes
+and seconds can be omitted, and decimals can be added. If a date with a
+time is represented, they should be separated by a literal ``T'', so noon
+on December 13, 2012 can be represented as 2012-12-13T12:00.
+
+@node Date Formatting Codes, Free-Form Dates, ISO 8601, Date Formats
@subsubsection Date Formatting Codes
@noindent
Year: ``1991'' for 1991, ``23'' for 23 AD.
@item YYYY
Year: ``1991'' for 1991, ``+23'' for 23 AD.
+@item ZYYY
+Year: ``1991'' for 1991, ``0023'' for 23 AD, ``0000'' for 1 BC.
+@item IYYY
+Year: ISO 8601 week-numbering year.
@item aa
Year: ``ad'' or blank.
@item AA
Day: `` 7'' for 7th day of month.
@item W
Weekday: ``0'' for Sunday, ``6'' for Saturday.
+@item w
+Weekday: ``1'' for Monday, ``7'' for Sunday.
@item WWW
Weekday: ``SUN'' for Sunday.
@item Www
Weekday: ``SUNDAY'' for Sunday.
@item Wwww
Weekday: ``Sunday'' for Sunday.
+@item Iww
+Week number: ISO 8601 week number, ``W01'' for week 1.
@item d
Day of year: ``34'' for Feb. 3.
@item ddd
Day of year: ``034'' for Feb. 3.
@item bdd
Day of year: `` 34'' for Feb. 3.
+@item T
+Letter: Literal ``T''.
@item h
Hour: ``5'' for 5 AM; ``17'' for 5 PM.
@item hh
@samp{p.m.}, and @samp{mid} are also understood. Obviously
@samp{noon} and @samp{midnight} are allowed only on 12:00:00.
The words @samp{noon}, @samp{mid}, and @samp{midnight} are also
-recognized with no number attached.
+recognized with no number attached. Midnight will represent the
+beginning of a day.
If there is no AM/PM indicator, the time is interpreted in 24-hour
format.
-To read the date portion, all words and numbers are isolated
-from the string; other characters are ignored. All words must
-be either month names or day-of-week names (the latter of which
-are ignored). Names can be written in full or as three-letter
+When reading the date portion, Calc first checks to see if it is an
+ISO 8601 week-numbering date; if the string contains an integer
+representing the year, a ``W'' followed by two digits for the week
+number, and an integer from 1 to 7 representing the weekday (in that
+order), then all other characters are ignored and this information
+determines the date. Otherwise, all words and numbers are isolated
+from the string; other characters are ignored. All words must be
+either month names or day-of-week names (the latter of which are
+ignored). Names can be written in full or as three-letter
abbreviations.
Large numbers, or numbers with @samp{+} or @samp{-} signs,
@samp{j<, h:mm:ss>} (Julian day plus time)
@item 9
@samp{YYddd< hh:mm:ss>} (Year-day format)
+@item 10
+@samp{ZYYY-MM-DD Www< hh:mm>} (Org mode format)
+@item 11
+@samp{IYYY-Iww-w<Thh:mm:ss>} (ISO 8601 week numbering format)
@end table
@node Truncating the Stack, Justification, Date Formats, Display Modes
the user-level @code{pwday} function described in the previous
section. It takes four arguments: The floating-point date value,
the corresponding six-element date list, the day-of-month number,
-and the weekday number (0-6).
+and the weekday number (0--6).
The default daylight saving hook ignores the time zone name, but a
more sophisticated hook could use different algorithms for different
@c 17
@item
-A prefix argument specifies a day number (0-6, 0-31, or 0-366).
+A prefix argument specifies a day number (0--6, 0--31, or 0--366).
@c 18
@item