Use @sc where appropriate. Document the

ranges of supported times more precisely.  Correct menu
spacing.  Document old Latin 12m/12pm tradition.  Remove list
of alphabetic time zone names, as it wasn't correct and people
shouldn't be relying on it anyway.  Relative items also
account for non-DST adjustments.  Fix some misspellings.

1 files changed, 45 insertions, 138 deletions

diff --git a/doc/getdate.texi b/doc/getdate.texi
index 0bcd35efe..5d64c27b6 100644
--- a/doc/getdate.texi
+++ b/doc/getdate.texi
@@ -30,25 +30,30 @@ or a week from Sunday, with feelings of helpless confusion.  @dots{}
 --- Robert Grudin, @cite{Time and the Art of Living}.
 @end quotation
 
-This section describes the textual date representations that GNU
+This section describes the textual date representations that @sc{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{getdate} function) is not described here.
 
-@cindex beginning of time, for Unix
-@cindex epoch, for Unix
-Although the date syntax here can represent any possible time since zero
-A.D., computer integers are not big enough for such a (comparatively)
-long time.  The earliest date semantically allowed on Unix systems is
-midnight, 1 January 1970 UCT.
+@cindex beginning of time, for @sc{posix}
+@cindex epoch, for @sc{posix}
+Although the date syntax here can represent any possible time since the
+year zero, computer integers often cannot represent such a wide range of
+time.  On @sc{posix} systems, the clock starts at 1970-01-01 00:00:00
+@sc{utc}: @sc{posix} does not require support for times before the
+@sc{posix} Epoch and times far in the future.  Traditional Unix systems
+have 32-bit signed @code{time_t} and can represent times from 1901-12-13
+20:45:52 through 2038-01-19 03:14:07 @sc{utc}.  Systems with 64-bit
+signed @code{time_t} can represent all the times in the known
+lifetime of the universe.
 
 @menu
 * General date syntax::            Common rules.
-* Calendar date items::             19 Dec 1994.
-* Time of day items::               9:20pm.
-* Time zone items::                 EST, DST, BST, UTC, ...
-* Day of week items::               Monday and others.
-* Relative items in date strings::  next tuesday, 2 years ago.
+* Calendar date items::            19 Dec 1994.
+* Time of day items::              9:20pm.
+* Time zone items::                @sc{est}, @sc{pdt}, @sc{gmt}, ...
+* Day of week items::              Monday and others.
+* Relative items in date strings:: next tuesday, 2 years ago.
 * Pure numbers in date strings::   19931219, 1440.
 * Authors of getdate::             Bellovin, Salz, Berets, et al.
 @end menu
@@ -113,7 +118,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     # ISO 8601.
+1972-09-24     # @sc{iso} 8601.
 72-9-24        # Assume 19xx for 69 through 99,
                # 20xx for 00 through 68.
 72-09-24       # Leading zeros are ignored.
@@ -136,9 +141,9 @@ sep 24
 
 Here are the rules.
 
-@cindex ISO 8601 date format
-@cindex date format, ISO 8601
-For numeric months, the ISO 8601 format
+@cindex @sc{iso} 8601 date format
+@cindex date format, @sc{iso} 8601
+For numeric months, the @sc{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
@@ -186,7 +191,7 @@ day.  Here are some examples, all of which represent the same time:
 20:02:0
 20:02
 8:02pm
-20:02-0500      # In EST (Eastern U.S. Standard Time).
+20:02-0500      # In @sc{est} (U.S. Eastern Standard Time).
 @end example
 
 More generally, the time of the day may be given as
@@ -206,6 +211,9 @@ or @samp{p.m.}), @var{hour} is restricted to run from 1 to 12, and
 indicates the first half of the day, @samp{pm} indicates the second
 half of the day.  In this notation, 12 is the predecessor of 1:
 midnight is @samp{12am} while noon is @samp{12pm}.
+(This is the zero-oriented interpretation of @samp{12am} and @samp{12pm},
+as opposed to the old tradition derived from Latin
+which uses @samp{12m} for noon and @samp{12pm} for midnight.)
 
 @cindex time zone correction
 @cindex minutes, time zone correction by
@@ -214,10 +222,10 @@ 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
 forces interpretation of the time relative to
-Coordinated Universal Time (UTC), overriding any previous
+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 the day may not be elided when a time zone correction
-is used.  This is the only way to specify a time zone correction by
+is used.  This is the best way to specify a time zone correction by
 fractional parts of an hour.
 
 Either @samp{am}/@samp{pm} or a time zone correction may be specified,
@@ -229,119 +237,18 @@ but not both.
 
 @cindex time zone item
 
-A @dfn{time zone item} specifies an international time zone, indicated by
-a small set of letters.  They are supported for backward compatibility reasons,
-but they are not recommended because they are ambiguous in practice:
-for example, the abbreviation @samp{EST} has different meanings in
-Australia and the United States.  Any included period is ignored.  Military
-time zone designations use a single letter.  Currently, only integral
-zone hours may be represented in a time zone item.  See the previous
-section for a finer control over the time zone correction.
-
-Here are many non-daylight-saving-time time zones, indexed by the zone
-hour value.
-
-@table @asis
-@item -1200
-@samp{Y} for militaries.
-@item -1100
-@samp{X} for militaries.
-@item -1000
-@samp{W} for militaries.
-@item -0900
-@samp{V} for militaries.
-@item -0800
-@samp{PST} for Pacific Standard, and
-@samp{U} for militaries.
-@item -0700
-@samp{MST} for Mountain Standard, and
-@samp{T} for militaries.
-@item -0600
-@samp{CST} for Central Standard, and
-@samp{S} for militaries.
-@item -0500
-@samp{EST} for Eastern Standard, and
-@samp{R} for militaries.
-@item -0400
-@samp{AST} for Atlantic Standard, and
-@samp{Q} for militaries.
-@item -0300
-@samp{P} for militaries.
-@item -0200
-@samp{O} for militaries.
-@item -0100
-@samp{N} for militaries.
-@item +0000
-@cindex Greenwich Mean Time
-@cindex Coordinated Universal Time
-@cindex Universal Coordinated Time
-@cindex Universal Time (Coordinated)
-@samp{GMT} for Greenwich Mean,
-@samp{UT} for Universal,
-@samp{UTC} for Coordinated Universal,
-@samp{WET} for Western European, and
-@samp{Z} for ISO 8601 and militaries.
-@item +0100
-@samp{A} for militaries,
-@samp{CET} for Central European,
-@samp{MET} for Midden Europesche Tijd (Dutch), and
-@samp{MEZ} for Mittel-Europ@"aische Zeit (German).
-@item +0200
-@samp{B} for militaries, and
-@samp{EET} for Eastern European.
-@item +0300
-@samp{C} for militaries.
-@item +0400
-@samp{D} for militaries.
-@item +0500
-@samp{E} for militaries.
-@item +0600
-@samp{F} for militaries.
-@item +0700
-@samp{G} for militaries.
-@item +0800
-@samp{H} for militaries.
-@item +0900
-@samp{I} for militaries, and
-@samp{JST} for Japan Standard.
-@item +1000
-@samp{GST} for Guam Standard, and
-@samp{K} for militaries.
-@item +1100
-@samp{L} for militaries.
-@item +1200
-@samp{M} for militaries, and
-@samp{NZST} for New Zealand Standard.
-@end table
-
-@cindex daylight-saving time
-Here are many daylight-saving time (DST) time zones,
-indexed by the zone hour value.  Also, by
-following a non-DST time zone by the string @samp{DST} in a separate word
-(that is, separated by some whitespace), the corresponding DST time zone
-may be specified.
-
-@table @asis
-@item -0700
-@samp{PDT} for Pacific Daylight.
-@item -0600
-@samp{MDT} for Mountain Daylight.
-@item -0500
-@samp{CDT} for Central Daylight.
-@item -0400
-@samp{EDT} for Eastern Daylight.
-@item -0300
-@samp{ADT} for Atlantic Daylight.
-@item +0100
-@samp{BST} for British Summer, and
-@samp{WEST} for Western European Summer.
-@item +0200
-@samp{CEST} for Central European Summer,
-@samp{MEST} for Midden Europesche S. Tijd (Dutch), and
-@samp{MESZ} for Mittel-Europ@"aische Sommerzeit (German).
-@item +1300
-@samp{NZDT} for New Zealand Daylight.
-@end table
+A @dfn{time zone item} specifies an international time zone, indicated
+by a small set of letters, e.g., @samp{UTC} for Coordinated Universal
+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.
+
+Time zone items are obsolescent and are not recommended, because they
+are ambiguous; for example, @samp{EST} has a different meaning in
+Australia than in the United States.  Instead, it's better to use
+unambiguous numeric time zone corrections like @samp{-0500}, as
+described in the previous section.
 
 
 @node Day of week items
@@ -409,7 +316,7 @@ The unit of time may be preceded by a multiplier, given as an optionally
 signed number.  Unsigned numbers are taken as positively signed.  No
 number at all implies 1 for a multiplier.  Following a relative item by
 the string @samp{ago} is equivalent to preceding the unit by a
-multiplicator with value @math{-1}.
+multiplier with value @math{-1}.
 
 @findex day @r{in date strings}
 @findex tomorrow @r{in date strings}
@@ -429,9 +336,9 @@ items, like in @samp{12:00 today}.  The string @samp{this} also has
 the meaning of a zero-valued time displacement, but is preferred in
 date strings like @samp{this thursday}.
 
-When a relative item causes the resulting date to cross the boundary
-between DST and non-DST (or vice-versa), the hour is adjusted according
-to the local time.
+When a relative item causes the resulting date to cross a boundary
+where the clocks were adjusted, typically for daylight-saving time,
+the resulting date and time are adjusted accordingly.
 
 
 @node Pure numbers in date strings
@@ -439,7 +346,7 @@ to the local time.
 
 @cindex pure numbers in date strings
 
-The precise intepretation of a pure decimal number depends
+The precise interpretation of a pure decimal number depends
 on the context in the date string.
 
 If the decimal number is of the form @var{yyyy}@var{mm}@var{dd} and no
@@ -474,7 +381,7 @@ year.
 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 GNU system were made by David MacKenzie, Jim Meyering,
+revisions for the @sc{gnu} system were made by David MacKenzie, Jim Meyering,
 Paul Eggert and others.
 
 @cindex Pinard, F.