From: Jay Belanger Date: Sun, 16 Dec 2012 02:07:30 +0000 (-0600) Subject: * doc/misc/calc.texi (ISO-8601): New section. X-Git-Tag: emacs-24.3.90~173^2~7^2~575 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=b9d8175e56d6e6a9acd336863f420bf7cd5a471a;p=emacs.git * doc/misc/calc.texi (ISO-8601): New section. (Date Formatting Codes): Mention new codes. (Standard Date Formats): Mention new formats. --- diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog index ecf3619db4b..1ca638bb7fe 100644 --- a/doc/misc/ChangeLog +++ b/doc/misc/ChangeLog @@ -1,3 +1,9 @@ +2012-12-16 Jay Belanger + + * calc.texi (ISO-8601): New section. + (Date Formatting Codes): Mention new codes. + (Standard Date Formats): Mention new formats. + 2012-12-14 Michael Albinus * tramp.texi (External methods): Move `adb' method here. diff --git a/doc/misc/calc.texi b/doc/misc/calc.texi index 5ed5212ad25..138ed23eae9 100644 --- a/doc/misc/calc.texi +++ b/doc/misc/calc.texi @@ -13417,12 +13417,91 @@ dates. @xref{Specifying Operators}. To avoid confusion with nameless 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 @@ -13463,6 +13542,10 @@ Year: ``91'' for 1991, `` 7'' for 2007, ``+23'' for 23 AD. 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 @@ -13511,6 +13594,8 @@ Day: ``07'' for 7th day of month. 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 @@ -13521,12 +13606,16 @@ Weekday: ``sun'' for Sunday. 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 @@ -13700,6 +13789,10 @@ command (@pxref{Mode Settings}). @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