[Emacs-diffs] /srv/bzr/emacs/trunk r111247: * doc/misc/calc.texi (ISO-8601): New section.

[Jay Belanger]

------------------------------------------------------------
revno: 111247
committer: Jay Belanger <address@hidden>
branch nick: trunk
timestamp: Sat 2012-12-15 20:07:30 -0600
message:
  * doc/misc/calc.texi (ISO-8601): New section.
    (Date Formatting Codes): Mention new codes.
    (Standard Date Formats): Mention new formats.
modified:
  doc/misc/ChangeLog
  doc/misc/calc.texi

=== modified file 'doc/misc/ChangeLog'
--- a/doc/misc/ChangeLog        2012-12-14 15:37:27 +0000
+++ b/doc/misc/ChangeLog        2012-12-16 02:07:30 +0000
@@ -1,3 +1,9 @@
+2012-12-16  Jay Belanger  <address@hidden>
+
+       * calc.texi (ISO-8601): New section.
+       (Date Formatting Codes): Mention new codes.
+       (Standard Date Formats): Mention new formats.
+
 2012-12-14  Michael Albinus  <address@hidden>
 
        * tramp.texi (External methods): Move `adb' method here.

=== modified file 'doc/misc/calc.texi'
--- a/doc/misc/calc.texi        2012-12-06 06:17:10 +0000
+++ b/doc/misc/calc.texi        2012-12-16 02:07:30 +0000
@@ -13417,12 +13417,91 @@
 functions, your date formats should avoid using the @samp{#} character.
 
 @menu
+* ISO-8601::
 * Date Formatting Codes::
 * Free-Form Dates::
 * Standard Date Formats::
 @end menu
 
address@hidden Date Formatting Codes, Free-Form Dates, Date Formats, Date 
Formats
address@hidden ISO-8601, Date Formatting Codes, Date Formats, Date Formats
address@hidden ISO-8601
+
address@hidden
address@hidden 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
+
address@hidden
+   @address@hidden@var{DD}
address@hidden example
+
address@hidden
+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 
+
address@hidden
+  @address@hidden
address@hidden example
+
address@hidden
+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 
+
address@hidden
+ @address@hidden@var{D}
address@hidden example
+
address@hidden
+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
+
address@hidden Date Formatting Codes, Free-Form Dates, ISO-8601, Date Formats
 @subsubsection Date Formatting Codes
 
 @noindent
@@ -13463,6 +13542,10 @@
 Year:  ``1991'' for 1991, ``23'' for 23 AD.
 @item YYYY
 Year:  ``1991'' for 1991, ``+23'' for 23 AD.
address@hidden ZYYY
+Year:  ``1991'' for 1991, ``0023'' for 23 AD., ``0000'' for 1 BC.
address@hidden IYYY
+Year:  ISO-8601 week-numbering year.
 @item aa
 Year:  ``ad'' or blank.
 @item AA
@@ -13511,6 +13594,8 @@
 Day:  `` 7'' for 7th day of month.
 @item W
 Weekday:  ``0'' for Sunday, ``6'' for Saturday.
address@hidden w
+Weekday:  ``1'' for Monday, ``7'' for Sunday.
 @item WWW
 Weekday:  ``SUN'' for Sunday.
 @item Www
@@ -13521,12 +13606,16 @@
 Weekday:  ``SUNDAY'' for Sunday.
 @item Wwww
 Weekday:  ``Sunday'' for Sunday.
address@hidden 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.
address@hidden T
+Letter:  Literal ``T''.
 @item h
 Hour:  ``5'' for 5 AM; ``17'' for 5 PM.
 @item hh
@@ -13700,6 +13789,10 @@
 @samp{j<, h:mm:ss>}  (Julian day plus time)
 @item 9
 @samp{YYddd< hh:mm:ss>}  (Year-day format)
address@hidden 10
address@hidden Www< hh:mm>} (Org mode format)
address@hidden 11
address@hidden< Thh:mm:ss>} (ISO-8601 week numbering format)
 @end table
 
 @node Truncating the Stack, Justification, Date Formats, Display Modes