cal: update man page

Update cal.1 with the new options --reform and --iso.

Also add information about the calendar systems used and
the difference between the --julian option and the Julian
calendar system.

Signed-off-by: J William Piggott <elseifthen@gmx.com>

1 files changed, 74 insertions, 9 deletions

diff --git a/misc-utils/cal.1 b/misc-utils/cal.1
index f1084edba..f99c6b495 100644
--- a/misc-utils/cal.1
+++ b/misc-utils/cal.1
@@ -34,7 +34,7 @@
 .\"
 .\"     @(#)cal.1	8.1 (Berkeley) 6/6/93
 .\"
-.TH CAL 1 "June 2015" "util-linux" "User Commands"
+.TH CAL 1 "January 2018" "util-linux" "User Commands"
 .SH NAME
 cal \- display a calendar
 .SH SYNOPSIS
@@ -52,6 +52,22 @@ month is displayed.
 .sp
 The \fImonth\fR may be specified as a number (1-12), as a month name or as an
 abbreviated month name according to the current locales.
+.sp
+Two different calendar systems are used, Gregorian and Julian.  These are
+nearly identical systems with Gregorian making a small adjustment to the
+frequency of leap years; this facilitates improved synchronization with solar
+events like the equinoxes.  The Gregorian calendar reform was introduced in
+1582, but its adoption continued up to 1923.  By default
+.B cal
+uses the adoption date of 3 Sept 1752.  From that date forward the Gregorian
+calendar is displayed; previous dates use the Julian calendar system.  11 days
+were removed at the time of adoption to bring the calendar in sync with solar
+events.  So Sept 1752 has a mix of Julian and Gregorian dates by which the 2nd
+is followed by the 14th (the 3rd through the 13th are absent).
+.sp
+Optionally, either the proleptic Gregorian calendar or the Julian calendar may
+be used exclusively.
+.RB See\  \-\-reform\  below.
 .SH OPTIONS
 .TP
 \fB\-1\fR, \fB\-\-one\fR
@@ -73,8 +89,60 @@ Display Sunday as the first day of the week.
 \fB\-m\fR, \fB\-\-monday\fR
 Display Monday as the first day of the week.
 .TP
+.B \-\-iso
+Display the proleptic Gregorian calendar exclusively.
+.RB See\  \-\-reform\  below.
+.TP
 \fB\-j\fR, \fB\-\-julian\fR
-Display Julian dates (days one-based, numbered from January 1).
+Use day-of-year numbering for all calendars.  These are also called ordinal
+days.  Ordinal days range from 1 to 366.  This option does not switch from the
+Gregorian to the Julian calendar system, that is controlled by the
+.BR \-\-reform\  option.
+.sp
+Sometimes Gregorian calendars using ordinal dates are referred to as Julian
+calendars.  This can be confusing due to the many date related conventions that
+use Julian in their name: (ordinal) julian date, julian (calendar) date,
+(astronomical) julian date, (modified) julian date, and more.  This option is
+named julian, because ordinal days are identified as julian by the POSIX
+standard.  However, be aware that
+.B cal
+also uses the Julian calendar system.
+.RB See\  DESCRIPTION\  above.
+.TP
+.BI \-\-reform\  val
+This option sets the adoption date of the Gregorian calendar reform.  Calendar
+dates previous to reform use the Julian calendar system.  Calendar dates
+after reform use the Gregorian calendar system.  The argument
+.I val
+can be:
+.RS
+.IP \(bu 2
+.I 1752
+- sets 3 September 1752 as the reform date (default).
+This is when the Gregorian calendar reform was adopted by the British Empire.
+.IP \(bu 2
+.I gregorian
+- display Gregorian calendars exclusively.  This special placeholder sets the
+reform date below the smallest year that
+.B cal
+can use; meaning all calendar output uses the Gregorian calendar system.  This
+is called the proleptic Gregorian calendar, because dates prior to the calendar
+system's creation use extrapolated values.
+.IP \(bu 2
+.I iso
+- alias of
+.IR gregorian .
+The ISO 8601 standard for the representation of dates and times in information
+interchange requires using the proleptic Gregorian calendar.
+.IP \(bu 2
+.I julian
+- display Julian calendars exclusively.  This special placeholder sets the reform date above the largest year that
+.B cal
+can use; meaning all
+calendar output uses the Julian calendar system.
+.PP
+.RB See\  \%DESCRIPTION\  above.
+.RE
 .TP
 \fB\-y\fR, \fB\-\-year\fR
 Display a calendar for the whole year.
@@ -148,14 +216,11 @@ See
 for more details about colorization configuration.
 .SH BUGS
 .PP
-The
+The default
 .B cal
-program uses the 3rd of September 1752 as the date of the Gregorian calendar
-reformation -- that is when it happened in Great Britain and its colonies
-(including what is now the USA).  Starting at that date, eleven days were eliminated
-by this reformation, so the calendar for that month is rather unusual.
-The actual historical dates at which the calendar reform happened in all the
-different countries (locales) are ignored.
+output uses 3 September 1752 as the Gregorian calendar reform date.  The
+historical reform  dates for the other locales, including its introduction in
+October 1582, are not implemented.
 .PP
 Alternative calendars, such as the Umm al-Qura, the Solar Hijri, the Ge'ez,
 or the lunisolar Hindu, are not supported.