[v3 PATCH 00/11] Pull Request - changelog

[v3 PATCH 00/11] Pull Request - changelog

[J William Piggott]

In my last post I suggested a path to implementing Karel's
idea of having complementary options --julian and --gregorian
that output their respective calendar systems exclusively.
IMO, having the capability for Julian calendar output is a
nice addition; and making proleptic Gregorian the default
output is the correct choice (reasons are given in the commit
log).

Having not received any reply, I went ahead with the
implementation, with one change involving Karel's original
request for volunteers. Specifically, the first and last bullet
points; which where:

* keep the current default "British Empire" behavior (Gregorian since
  September 1752)

* later (after warning in release notes) we can make --gregorian as
  the default

During implementation I considered these issues:

* to do that we'd be creating two new options --iso, and an
  alias --gregorian; these would become non-functional once
  they were made the default. Just like the current situation
  with --one and --sunday.

* this change is unlikely to affect downstream maintainers

* end users are the ones that may be caught out by it

* a release note warning that some future version of cal(1)
  will change the default output is unlikely to reach the end
  users.

So I think it would be better to just rip-the-band-aid-off, as
they say, and make it the default straight away. I added a
prominent note near the top of the man page, and of course do
the same in the release notes highlights.

This patch set breaks cal(1) tests. I will look at fixing them
if/when it is accepted.

Indirectly, the current tests are broken. I think this
supports some of the changes in this patch set:

The tests author seemed to believe that the -1 and -s options
actually do something, despite the 'expected' output showing
otherwise. While testing this patch set I thought the same
thing; I tried to figure out what these two options do; which
is nothing. I think this is good evidence to support removing
them.

The tests author also seems to believe that the -j option
switches from the Gregorian calendar system to the Julian
calendar system. Making comments to that affect and using it
in tests involving the year 1752; a year which uses both
calendar systems. I think this is good evidence to support
renaming --julian to --ordinal.

If developers for the project are being confused by these
options, than what chance do end users have? So that's my case
for making these changes.

Also while pounding on cal(1), to see if these patches broke
anything, I found a few other issues and fixed them as well.
The man page was quite sparse, for example having no explanation
for the -w argument, so rewrote much of it.

v2 to v3 changelog
* make proleptic Gregorian the default
* extensive man page updates
* rename --julian to --ordinal
* add private (for now) --caesar option for exclusive Julian calendar
* allow -w to accept its argument
* update mutually exclusive options
* add short versions for the new options
* remove non-functional options
* fix broken week calculations

v1 to v2 changelog
 * fix typo in v1
 * move REFORMATION_YEAR to the control struct
 * add more about the --1752-reform option to man page
 * add a second patch with minor style and wording changes


The following changes since commit 43afa84581de8984aa00ef2e9208198929f72ddf:

  lib/mbsalign: encode \x to \xecx (2017-12-20 13:01:43 +0100)

are available in the git repository at:

  git@github.com:jwpi/util-linux.git 171229

for you to fetch changes up to 22540b0a23283925ce4b13c13839e4dd2172bd1d:

  cal: fix week calculations for --1752-reform (2018-01-01 21:25:16 -0500)

----------------------------------------------------------------
J William Piggott (11):
      cal: change default output format
      cal: change reformation to reform
      cal: update man page and usage()
      cal: rename --julian to --ordinal
      cal: add private --caesar option
      cal: make -w accept its optional argument
      cal: update mutually exclusive options
      cal: add short versions of new options
      cal: remove the non-functional options
      cal: fix first week calculation
      cal: fix week calculations for --1752-reform

 Documentation/deprecated.txt |   6 ++
 misc-utils/cal.1             | 164 ++++++++++++++++++++++------------
 misc-utils/cal.c             | 208 ++++++++++++++++++++++++-------------------
 3 files changed, 233 insertions(+), 145 deletions(-)

[v3 PATCH 01/11] cal: change default output format

[J William Piggott]

Change the default calendar system to proleptic Gregorian;
this makes it consistent with ISO 8601, date(1), and  most
other conventions.

Also add the --1752-reform option to keep the old default
output available.

The current POSIX description for cal(1) could be interpreted as saying that a
1752 reform is the default format. The history of the description seems to
indicate otherwise. Issue 2 introduced cal(1) and required the Gregorian
format:

http://pubs.opengroup.org/onlinepubs/007908799/xcu/cal.html
 > DESCRIPTION
 >
 >    The cal utility writes a Gregorian calendar to standard output.

The reason for the change in Issue 6 was to *allow* Julian output:

http://pubs.opengroup.org/onlinepubs/9699919799/utilities/cal.html
 > The DESCRIPTION is updated to allow for traditional behavior for years
 > before the adoption of the Gregorian calendar.

So it seems the intent was to allow old implementations, not to define a
default calendar system to use.

Having the default calendar system comply with ISO 8601 makes cal(1) more
compatible with the rest of the system.

Signed-off-by: J William Piggott <elseifthen@gmx.com>
---
 misc-utils/cal.1 | 22 +++++++++----
 misc-utils/cal.c | 94 +++++++++++++++++++++++++++++++++-----------------------
 2 files changed, 72 insertions(+), 44 deletions(-)

diff --git a/misc-utils/cal.1 b/misc-utils/cal.1
index f1084edba..2499483b6 100644
--- a/misc-utils/cal.1
+++ b/misc-utils/cal.1
@@ -52,15 +52,24 @@ 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
+Since v2.32 the default calendar system has changed to proleptic Gregorian;
+this makes it consistent with ISO 8601, date(1), and most other conventions.
+The old default output is still available by using the
+.BR \-\-1752-reform\  option.
 .SH OPTIONS
 .TP
 \fB\-1\fR, \fB\-\-one\fR
-Display single month output.
-(This is the default.)
+Display single month output (default).
 .TP
 \fB\-3\fR, \fB\-\-three\fR
 Display three months spanning the date.
 .TP
+.B \-\-1752-reform
+Display calendars based upon the Chesterfield's Act.
+This means that dates previous to 3 Sept 1752 will be Julian calendar dates.
+.RB See \ BUGS \ below.
+.TP
 \fB\-n , \-\-months\fR \fInumber\fR
 Display \fInumber\fR of months, starting from the month containing the date.
 .TP
@@ -148,14 +157,15 @@ See
 for more details about colorization configuration.
 .SH BUGS
 .PP
-The
-.B cal
-program uses the 3rd of September 1752 as the date of the Gregorian calendar
+.RB The\  \-\-1752-reform
+option 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.
+different countries (locales), including its introduction by Pope Gregory XIII
+in October 1582, are ignored. The Gregorian calendar is a refinement to the
+Julian calendar improving its synchronization with solar cycles.
 .PP
 Alternative calendars, such as the Umm al-Qura, the Solar Hijri, the Ge'ez,
 or the lunisolar Hindu, are not supported.
diff --git a/misc-utils/cal.c b/misc-utils/cal.c
index 39f2bdcba..2dfdaa25b 100644
--- a/misc-utils/cal.c
+++ b/misc-utils/cal.c
@@ -160,7 +160,6 @@ enum {
 	DECEMBER
 };
 
-#define REFORMATION_YEAR	1752		/* Signed-off-by: Lord Chesterfield */
 #define REFORMATION_MONTH	SEPTEMBER
 #define	NUMBER_MISSING_DAYS	11		/* 11 day correction */
 #define YDAY_AFTER_MISSING	258             /* 14th in Sep 1752 */
@@ -206,6 +205,7 @@ struct cal_control {
 	const char *full_month[MONTHS_IN_YEAR];	/* month names */
 	const char *abbr_month[MONTHS_IN_YEAR];	/* abbreviated month names */
 
+	int reform_year;		/* Gregorian reform year */
 	int colormode;			/* day and week number highlight */
 	int num_months;			/* number of requested months */
 	int span_months;		/* span the date */
@@ -230,7 +230,7 @@ struct cal_month {
 };
 
 /* function prototypes */
-static int leap_year(int32_t year);
+static int leap_year(const struct cal_control *ctl, int32_t year);
 static int monthname_to_number(struct cal_control *ctl, const char *name);
 static void headers_init(struct cal_control *ctl);
 static void cal_fill_month(struct cal_month *month, const struct cal_control *ctl);
@@ -238,8 +238,10 @@ static void cal_output_header(struct cal_month *month, const struct cal_control
 static void cal_output_months(struct cal_month *month, const struct cal_control *ctl);
 static void monthly(const struct cal_control *ctl);
 static void yearly(const struct cal_control *ctl);
-static int day_in_year(int day, int month, int32_t year);
-static int day_in_week(int day, int month, int32_t year);
+static int day_in_year(const struct cal_control *ctl, int day,
+		       int month, int32_t year);
+static int day_in_week(const struct cal_control *ctl, int day,
+		       int month, int32_t year);
 static int week_number(int day, int month, int32_t year, const struct cal_control *ctl);
 static int week_to_day(const struct cal_control *ctl);
 static int center_str(const char *src, char *dest, size_t dest_size, size_t width);
@@ -252,7 +254,9 @@ int main(int argc, char **argv)
 	char *term;
 	time_t now;
 	int ch = 0, yflag = 0, Yflag = 0;
+
 	static struct cal_control ctl = {
+		.reform_year = -1,		/* def. proleptic Gregorian */
 		.weekstart = SUNDAY,
 		.num_months = 1,		/* default is "cal -1" */
 		.span_months = 0,
@@ -265,7 +269,8 @@ int main(int argc, char **argv)
 	};
 
 	enum {
-		OPT_COLOR = CHAR_MAX + 1
+		OPT_1752_REFORM = CHAR_MAX + 1,
+		OPT_COLOR
 	};
 
 	static const struct option longopts[] = {
@@ -279,6 +284,7 @@ int main(int argc, char **argv)
 		{"year", no_argument, NULL, 'y'},
 		{"week", optional_argument, NULL, 'w'},
 		{"color", optional_argument, NULL, OPT_COLOR},
+		{"1752-reform", no_argument, NULL, OPT_1752_REFORM},
 		{"version", no_argument, NULL, 'V'},
 		{"twelve", no_argument, NULL, 'Y'},
 		{"help", no_argument, NULL, 'h'},
@@ -335,7 +341,8 @@ int main(int argc, char **argv)
 		val.string = nl_langinfo(_NL_TIME_WEEK_1STDAY);
 
 		wfd = val.word;
-		wfd = day_in_week(wfd % 100, (wfd / 100) % 100, wfd / (100 * 100));
+		wfd = day_in_week(&ctl, wfd % 100, (wfd / 100) % 100,
+				  wfd / (100 * 100));
 		ctl.weekstart = (wfd + *nl_langinfo(_NL_TIME_FIRST_WEEKDAY) - 1) % DAYS_IN_WEEK;
 	}
 #endif
@@ -390,6 +397,9 @@ int main(int argc, char **argv)
 				ctl.colormode = colormode_or_err(optarg,
 						_("unsupported color mode"));
 			break;
+		case OPT_1752_REFORM:
+			ctl.reform_year = 1752;
+			break;
 		case 'V':
 			printf(UTIL_LINUX_VERSION);
 			return EXIT_SUCCESS;
@@ -451,10 +461,12 @@ int main(int argc, char **argv)
 		if (ctl.req.year == INT32_MAX)
 			errx(EXIT_FAILURE, _("illegal year value"));
 		if (ctl.req.day) {
-			int dm = days_in_month[leap_year(ctl.req.year)][ctl.req.month];
+			int dm = days_in_month[leap_year(&ctl, ctl.req.year)]
+					      [ctl.req.month];
 			if (ctl.req.day > dm)
 				errx(EXIT_FAILURE, _("illegal day value: use 1-%d"), dm);
-			ctl.req.day = day_in_year(ctl.req.day, ctl.req.month, ctl.req.year);
+			ctl.req.day = day_in_year(&ctl, ctl.req.day,
+						  ctl.req.month, ctl.req.year);
 		} else if ((int32_t) (local_time->tm_year + 1900) == ctl.req.year) {
 			ctl.req.day = local_time->tm_yday + 1;
 		}
@@ -476,7 +488,7 @@ int main(int argc, char **argv)
 
 	if (0 < ctl.req.week) {
 		int yday = week_to_day(&ctl);
-		int leap = leap_year(ctl.req.year);
+		int leap = leap_year(&ctl, ctl.req.year);
 		int m = 1;
 
 		if (yday < 1)
@@ -532,9 +544,9 @@ int main(int argc, char **argv)
 }
 
 /* leap year -- account for gregorian reformation in 1752 */
-static int leap_year(int32_t year)
+static int leap_year(const struct cal_control *ctl, int32_t year)
 {
-	if (year <= REFORMATION_YEAR)
+	if (year <= ctl->reform_year)
 		return !(year % 4);
 	else
 		return ( !(year % 4) && (year % 100) ) || !(year % 400);
@@ -618,15 +630,15 @@ static void headers_init(struct cal_control *ctl)
 
 static void cal_fill_month(struct cal_month *month, const struct cal_control *ctl)
 {
-	int first_week_day = day_in_week(1, month->month, month->year);
+	int first_week_day = day_in_week(ctl, 1, month->month, month->year);
 	int month_days;
 	int i, j, weeklines = 0;
 
 	if (ctl->julian)
-		j = day_in_year(1, month->month, month->year);
+		j = day_in_year(ctl, 1, month->month, month->year);
 	else
 		j = 1;
-	month_days = j + days_in_month[leap_year(month->year)][month->month];
+	month_days = j + days_in_month[leap_year(ctl, month->year)][month->month];
 
 	/* True when Sunday is not first day in the output week. */
 	if (ctl->weekstart) {
@@ -644,7 +656,9 @@ static void cal_fill_month(struct cal_month *month, const struct cal_control *ct
 			continue;
 		}
 		if (j < month_days) {
-			if (month->year == REFORMATION_YEAR && month->month == REFORMATION_MONTH && (j == 3 || j == 247))
+			if (month->year == ctl->reform_year &&
+			    month->month == REFORMATION_MONTH &&
+			    (j == 3 || j == 247))
 				j += NUMBER_MISSING_DAYS;
 			month->days[i] = j;
 			j++;
@@ -726,9 +740,9 @@ static void cal_output_months(struct cal_month *month, const struct cal_control
 				if (ctl->julian)
 					reqday = ctl->req.day;
 				else
-					reqday =
-					    ctl->req.day + 1 - day_in_year(1, i->month,
-									   i->year);
+					reqday = ctl->req.day + 1 -
+						 day_in_year(ctl, 1, i->month,
+							     i->year);
 			}
 
 			if (ctl->weektype) {
@@ -847,11 +861,12 @@ static void yearly(const struct cal_control *ctl)
  * day_in_year --
  *	return the 1 based day number within the year
  */
-static int day_in_year(int day, int month, int32_t year)
+static int day_in_year(const struct cal_control *ctl,
+		       int day, int month, int32_t year)
 {
 	int i, leap;
 
-	leap = leap_year(year);
+	leap = leap_year(ctl, year);
 	for (i = 1; i < month; i++)
 		day += days_in_month[leap][i];
 	return day;
@@ -864,7 +879,8 @@ static int day_in_year(int day, int month, int32_t year)
  *	3 Sep. 1752 through 13 Sep. 1752, and returns invalid weekday
  *	during the period of 11 days.
  */
-static int day_in_week(int day, int month, int32_t year)
+static int day_in_week(const struct cal_control *ctl, int day,
+		       int month, int32_t year)
 {
 	/*
 	* The magic constants in the reform[] array are, in a simplified
@@ -886,20 +902,21 @@ static int day_in_week(int day, int month, int32_t year)
 	static const int reform[] = { 0, 3, 2, 5, 0, 3, 5, 1, 4, 6, 2, 4 };
 	static const int old[]    = { 5, 1, 0, 3, 5, 1, 3, 6, 2, 4, 0, 2 };
 
-	if (year != REFORMATION_YEAR + 1)
+	if (year != ctl->reform_year + 1)
 		year -= month < MARCH;
 	else
 		year -= (month < MARCH) + 14;
-	if (REFORMATION_YEAR < year
-	    || (year == REFORMATION_YEAR && REFORMATION_MONTH < month)
-	    || (year == REFORMATION_YEAR && month == REFORMATION_MONTH && 13 < day)) {
+	if (ctl->reform_year < year
+	    || (year == ctl->reform_year && REFORMATION_MONTH < month)
+	    || (year == ctl->reform_year
+	    && month == REFORMATION_MONTH && 13 < day)) {
 		int64_t long_year = year;
-		return (long_year + (year / 4) - (year / 100) + (year / 400) + reform[month - 1] +
-			day) % DAYS_IN_WEEK;
+		return (long_year + (year / 4) - (year / 100) + (year / 400) +
+			reform[month - 1] + day) % DAYS_IN_WEEK;
 	}
-	if (year < REFORMATION_YEAR
-	    || (year == REFORMATION_YEAR && month < REFORMATION_MONTH)
-	    || (year == REFORMATION_YEAR && month == REFORMATION_MONTH && day < 3))
+	if (year < ctl->reform_year
+	    || (year == ctl->reform_year && month < REFORMATION_MONTH)
+	    || (year == ctl->reform_year && month == REFORMATION_MONTH && day < 3))
 		return (year + year / 4 + old[month - 1] + day) % DAYS_IN_WEEK;
 	return NONEDAY;
 }
@@ -914,7 +931,7 @@ static int day_in_week(int day, int month, int32_t year)
 static int week_number(int day, int month, int32_t year, const struct cal_control *ctl)
 {
 	int fday = 0, yday;
-	const int wday = day_in_week(1, JANUARY, year);
+	const int wday = day_in_week(ctl, 1, JANUARY, year);
 
 	if (ctl->weektype & WEEK_NUM_ISO)
 		fday = wday + (wday >= FRIDAY ? -2 : 5);
@@ -930,8 +947,8 @@ static int week_number(int day, int month, int32_t year, const struct cal_contro
 	if (day > DAYS_IN_MONTH)
 		month = JANUARY;
 
-	yday = day_in_year(day,month,year);
-	if (year == REFORMATION_YEAR && yday >= YDAY_AFTER_MISSING)
+	yday = day_in_year(ctl, day, month, year);
+	if (year == ctl->reform_year && yday >= YDAY_AFTER_MISSING)
 		fday -= NUMBER_MISSING_DAYS;
 
 	/* Last year is last year */
@@ -942,10 +959,10 @@ static int week_number(int day, int month, int32_t year, const struct cal_contro
 	 * days than 365 making this check invalid, but reformation year ended
 	 * on Sunday and in week 51, so it's ok here. */
 	if (ctl->weektype == WEEK_NUM_ISO && yday >= 363
-	    && day_in_week(day, month, year) >= MONDAY
-	    && day_in_week(day, month, year) <= WEDNESDAY
-	    && day_in_week(31, DECEMBER, year) >= MONDAY
-	    && day_in_week(31, DECEMBER, year) <= WEDNESDAY)
+	    && day_in_week(ctl, day, month, year) >= MONDAY
+	    && day_in_week(ctl, day, month, year) <= WEDNESDAY
+	    && day_in_week(ctl, 31, DECEMBER, year) >= MONDAY
+	    && day_in_week(ctl, 31, DECEMBER, year) <= WEDNESDAY)
 		return week_number(1, JANUARY, year + 1, ctl);
 
 	return (yday + fday) / DAYS_IN_WEEK;
@@ -962,7 +979,7 @@ static int week_to_day(const struct cal_control *ctl)
 {
 	int yday, wday;
 
-	wday = day_in_week(1, JANUARY, ctl->req.year);
+	wday = day_in_week(ctl, 1, JANUARY, ctl->req.year);
 	yday = ctl->req.week * DAYS_IN_WEEK - wday;
 
 	if (ctl->weektype & WEEK_NUM_ISO)
@@ -1022,6 +1039,7 @@ static void __attribute__((__noreturn__)) usage(void)
 	fputs(_(" -y, --year            show the whole year\n"), out);
 	fputs(_(" -Y, --twelve          show the next twelve months\n"), out);
 	fputs(_(" -w, --week[=<num>]    show US or ISO-8601 week numbers\n"), out);
+	fputs(_("     --1752-reform     use Chesterfield's Act format\n"), out);
 	fputs(_("     --color[=<when>]  colorize messages (auto, always or never)\n"), out);
 	fprintf(out,
 	        "                         %s\n", USAGE_COLORS_DEFAULT);

[v3 PATCH 02/11] cal: change reformation to reform

[J William Piggott]

The proper term is calendar reform:
https://en.wikipedia.org/wiki/Calendar_reform

The term reformation is mostly associated with religion.

Also fix the reform[] array comment
and remove some extraneous tabs/spaces.

Signed-off-by: J William Piggott <elseifthen@gmx.com>
---
 misc-utils/cal.1 |  2 +-
 misc-utils/cal.c | 42 ++++++++++++++++++++++--------------------
 2 files changed, 23 insertions(+), 21 deletions(-)

diff --git a/misc-utils/cal.1 b/misc-utils/cal.1
index 2499483b6..d35b356d2 100644
--- a/misc-utils/cal.1
+++ b/misc-utils/cal.1
@@ -161,7 +161,7 @@ for more details about colorization configuration.
 option 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.
+by this reform, 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), including its introduction by Pope Gregory XIII
 in October 1582, are ignored. The Gregorian calendar is a refinement to the
diff --git a/misc-utils/cal.c b/misc-utils/cal.c
index 2dfdaa25b..cf05ecda3 100644
--- a/misc-utils/cal.c
+++ b/misc-utils/cal.c
@@ -160,23 +160,23 @@ enum {
 	DECEMBER
 };
 
-#define REFORMATION_MONTH	SEPTEMBER
-#define	NUMBER_MISSING_DAYS	11		/* 11 day correction */
+#define REFORM_MONTH		SEPTEMBER
+#define NUMBER_MISSING_DAYS	11		/* 11 day correction */
 #define YDAY_AFTER_MISSING	258             /* 14th in Sep 1752 */
 
 #define MONTHS_IN_YEAR		DECEMBER
 #define DAYS_IN_MONTH		31
-#define	MAXDAYS			42		/* slots in a month array */
-#define	SPACE			-1		/* used in day array */
+#define MAXDAYS			42		/* slots in a month array */
+#define SPACE			-1		/* used in day array */
 
 #define SMALLEST_YEAR		1
 
-#define	DAY_LEN			3		/* 3 spaces per day */
-#define	WEEK_LEN		(DAYS_IN_WEEK * DAY_LEN)
+#define DAY_LEN			3		/* 3 spaces per day */
+#define WEEK_LEN		(DAYS_IN_WEEK * DAY_LEN)
 #define MONTHS_IN_YEAR_ROW	3		/* month columns in year view */
-#define WNUM_LEN                3
+#define WNUM_LEN		3
 
-#define FMT_ST_CHARS 300	/* 90 suffices in most locales */
+#define FMT_ST_CHARS		300	/* 90 suffices in most locales */
 
 static const int days_in_month[2][13] = {
 	{0, 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31},
@@ -543,7 +543,7 @@ int main(int argc, char **argv)
 	return EXIT_SUCCESS;
 }
 
-/* leap year -- account for gregorian reformation in 1752 */
+/* leap year -- account for gregorian reform in 1752 */
 static int leap_year(const struct cal_control *ctl, int32_t year)
 {
 	if (year <= ctl->reform_year)
@@ -657,7 +657,7 @@ static void cal_fill_month(struct cal_month *month, const struct cal_control *ct
 		}
 		if (j < month_days) {
 			if (month->year == ctl->reform_year &&
-			    month->month == REFORMATION_MONTH &&
+			    month->month == REFORM_MONTH &&
 			    (j == 3 || j == 247))
 				j += NUMBER_MISSING_DAYS;
 			month->days[i] = j;
@@ -875,7 +875,7 @@ static int day_in_year(const struct cal_control *ctl,
 /*
  * day_in_week
  *	return the 0 based day number for any date from 1 Jan. 1 to
- *	31 Dec. 9999.  Assumes the Gregorian reformation eliminates
+ *	31 Dec. 9999.  Assumes the Gregorian reform eliminates
  *	3 Sep. 1752 through 13 Sep. 1752, and returns invalid weekday
  *	during the period of 11 days.
  */
@@ -886,8 +886,11 @@ static int day_in_week(const struct cal_control *ctl, int day,
 	* The magic constants in the reform[] array are, in a simplified
 	* sense, the remaining days after slicing into one week periods the total
 	* days from the beginning of the year to the target month. That is,
-	* weeks + reform[] days gets us to the target month. The exception is,
-	* that for the months past February 'DOY - 1' must be used.
+	* weeks + reform[] days gets us to the target month. Subtract one from
+	* the total days, before removing full weeks, to count the first day of
+	* the year. The exception is, the first two months need an extra day,
+	* because they are considered part of the previous year in the leap
+	* year handling scheme.
 	*
 	*   DoY (Day of Year): total days to the target month
 	*
@@ -907,16 +910,15 @@ static int day_in_week(const struct cal_control *ctl, int day,
 	else
 		year -= (month < MARCH) + 14;
 	if (ctl->reform_year < year
-	    || (year == ctl->reform_year && REFORMATION_MONTH < month)
-	    || (year == ctl->reform_year
-	    && month == REFORMATION_MONTH && 13 < day)) {
+	    || (year == ctl->reform_year && REFORM_MONTH < month)
+	    || (year == ctl->reform_year && month == REFORM_MONTH && 13 < day)) {
 		int64_t long_year = year;
 		return (long_year + (year / 4) - (year / 100) + (year / 400) +
 			reform[month - 1] + day) % DAYS_IN_WEEK;
 	}
 	if (year < ctl->reform_year
-	    || (year == ctl->reform_year && month < REFORMATION_MONTH)
-	    || (year == ctl->reform_year && month == REFORMATION_MONTH && day < 3))
+	    || (year == ctl->reform_year && month < REFORM_MONTH)
+	    || (year == ctl->reform_year && month == REFORM_MONTH && day < 3))
 		return (year + year / 4 + old[month - 1] + day) % DAYS_IN_WEEK;
 	return NONEDAY;
 }
@@ -955,8 +957,8 @@ static int week_number(int day, int month, int32_t year, const struct cal_contro
 	if (yday + fday < DAYS_IN_WEEK)
 		return week_number(31, DECEMBER, year - 1, ctl);
 
-	/* Or it could be part of the next year.  The reformation year had less
-	 * days than 365 making this check invalid, but reformation year ended
+	/* Or it could be part of the next year.  The reform year had less
+	 * days than 365 making this check invalid, but reform year ended
 	 * on Sunday and in week 51, so it's ok here. */
 	if (ctl->weektype == WEEK_NUM_ISO && yday >= 363
 	    && day_in_week(ctl, day, month, year) >= MONDAY

[v3 PATCH 03/11] cal: update man page and usage()

[J William Piggott]

Signed-off-by: J William Piggott <elseifthen@gmx.com>
---
 misc-utils/cal.1 | 134 ++++++++++++++++++++++++++++++++++++-------------------
 misc-utils/cal.c |   6 +--
 2 files changed, 91 insertions(+), 49 deletions(-)

diff --git a/misc-utils/cal.1 b/misc-utils/cal.1
index d35b356d2..7e917886c 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 "December 2017" "util-linux" "User Commands"
 .SH NAME
 cal \- display a calendar
 .SH SYNOPSIS
@@ -44,19 +44,40 @@ cal \- display a calendar
 .br
 .B cal
 [options]
-.RI <timestamp|monthname>
+.RI [ timestamp | month_name ]
 .SH DESCRIPTION
-.B cal
-displays a simple calendar.  If no arguments are specified, the current
-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
 Since v2.32 the default calendar system has changed to proleptic Gregorian;
 this makes it consistent with ISO 8601, date(1), and most other conventions.
 The old default output is still available by using the
 .BR \-\-1752-reform\  option.
+.sp
+If no arguments are specified, a calendar for the current 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 locale.
+.RI The \ year " must be greater than 0."
+.sp
+Timestamps are ISO like, and must be quoted.  For example: \%"2012-09-22\ 16:34:22"
+.RB See \ PARAMETERS \ below.
+.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.
+.sp
+.RB The\  \-\-1752-reform
+option uses the Gregorian calendar reform 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 13th
+are absent).
+.sp
+The default calendar system is proleptic Gregorian;  this means that dates
+previous to any calendar reform use extrapolated Gregorian dates instead of
+Julian calendar dates.
+
 .SH OPTIONS
 .TP
 \fB\-1\fR, \fB\-\-one\fR
@@ -74,7 +95,7 @@ This means that dates previous to 3 Sept 1752 will be Julian calendar dates.
 Display \fInumber\fR of months, starting from the month containing the date.
 .TP
 \fB\-S, \fB\-\-span\fR
-Display months spanning the date.
+Span the date when displaying multiple months.
 .TP
 \fB\-s\fR, \fB\-\-sunday\fR
 Display Sunday as the first day of the week.
@@ -83,7 +104,15 @@ Display Sunday as the first day of the week.
 Display Monday as the first day of the week.
 .TP
 \fB\-j\fR, \fB\-\-julian\fR
-Display Julian dates (days one-based, numbered from January 1).
+Use day-of-year numbering for all calendar types.  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 Gregorian
+epoch option
+.BR \%\-\-1752-reform .
+Sometimes Gregorian calendars using ordinal dates are referred to as Julian
+calendars.  This can be confusing because there are many date related
+conventions that use Julian in their name: (ordinal) julian date, julian
+(calendar) date, (astronomical) julian date, (modified) julian date, and more.
 .TP
 \fB\-y\fR, \fB\-\-year\fR
 Display a calendar for the whole year.
@@ -92,13 +121,23 @@ Display a calendar for the whole year.
 Display a calendar for the next twelve months.
 .TP
 \fB\-w\fR, \fB\-\-week\fR[=\fInumber\fR]
-Display week numbers in the calendar (US or ISO-8601).
+Display the week number in the left most column of each month.
+If the
+.I number
+argument and only a year parameter are given, then the month containing that
+week will be displayed and its number highlighted.  Otherwise, the week number
+will be highlighted only if its month is displayed.  For example, if the
+.B \-\-year
+option is used.
+.RB See\  \-\-color.
 .TP
 \fB\-\-color\fR[=\fIwhen\fR]
-Colorize the output.  The optional argument \fIwhen\fP
-can be \fBauto\fR, \fBnever\fR or \fBalways\fR.  If the \fIwhen\fR argument is omitted,
-it defaults to \fBauto\fR.  The colors can be disabled; for the current built-in default
-see the \fB\-\-help\fR output.  See also the \fBCOLORS\fR section.
+Control day/week highlighting.  The optional argument \fIwhen\fP can be
+\fBauto\fR, \fBnever\fR or \fBalways\fR.  If the \fIwhen\fR argument is
+omitted, it defaults to \fBauto\fR.  Auto means it is on if the output is to a
+terminal, otherwise it is off.   Colors could be disabled; the current built-in
+default is shown in the \fB\-\-help\fR output for this option.  See
+\fBCOLORS\fR below.
 .TP
 \fB\-V\fR, \fB\-\-version\fR
 Display version information and exit.
@@ -108,43 +147,51 @@ Display help text and exit.
 .SH PARAMETERS
 .TP
 \fBSingle digits-only parameter (e.g. 'cal 2020')\fR
-Specifies the \fIyear\fR to be displayed; note the year must be fully specified:
+Specifies the year to be displayed and must be greater than 0.  The year must
+be fully specified:
 .B "cal 89"
 will not display a calendar for 1989.
 .TP
 \fBSingle string parameter (e.g. 'cal tomorrow' or 'cal August')\fR
-Specifies \fItimestamp\fR or a \fImonth name\fR (or abbreviated name) according to the current
-locales.
+Can be a timestamp, relative time, month name, or abbreviated month name
+according to the current locale.  String parameters need to be in quotes if
+they contain any spaces.
+.sp
+Timestamps are ISO like, and must be quoted.  For example: \%"2012-09-22\ 16:34:22"
 .sp
-The special placeholders are accepted when parsing timestamp, "now" may be used
-to refer to the current time, "today", "yesterday", "tomorrow" refer to of the
-current day, the day before or the next day, respectively.
+Relative date specifications are also accepted, in this case "+" is evaluated
+to the current time plus the specified time span.  Correspondingly, a time span
+that is prefixed with "-" is evaluated to the current time minus the specified
+time span; it must be preceded by "--" to indicate the end of options, for
+example "-- -2days".  Alternately it may be suffixed with a space and the word
+"ago" (for example "1 week ago").
 .sp
-The relative date specifications are also accepted, in this case "+" is
-evaluated to the current time plus the specified time span. Correspondingly, a
-time span that is prefixed with "-" is evaluated to the current time minus the
-specified time span, for example '+2days'. Instead of prefixing the time span
-with "+" or "-", it may also be suffixed with a space and the word "left" or
-"ago" (for example '1 week ago').
+These special placeholders are accepted: "now", "today", "yesterday", and
+"tomorrow" refer to the current time, current day, the day before, or the next
+day respectively.
 .TP
 \fBTwo parameters (e.g. 'cal 11 2020')\fR
-Denote the \fImonth\fR (1 - 12) and \fIyear\fR.
+Denote the month (1 - 12) and year.
 .TP
 \fBThree parameters (e.g. 'cal 25 11 2020')\fR
-Denote the \fIday\fR (1-31), \fImonth and \fIyear\fR, and the day will be
-highlighted if the calendar is displayed on a terminal.  If no parameters are
-specified, the current month's calendar is displayed.
+Denote the day (1-31), month and year, and the day will be
+highlighted.
+.RB See\  \-\-color.
+.TP
+If no parameters are specified, the current month's calendar is displayed.
 .SH NOTES
 A year starts on January 1.  The first day of the week is determined by the
-locale.
+locale or the
+.BR \-\-sunday \ and \ \-\-monday \ options.
 .PP
-The week numbering depends on the choice of the first day of the week.  If Sunday
-(the default) is used for the first day of the week, then the customary North
-American numbering will be used, i.e. the first Sunday of the year starts the
-first week.  If Monday is selected, then the ISO-8601 standard week numbering
+The week numbering depends on the choice of the first day of the week.  If it
+is Sunday
+(the default) then the customary North
+American numbering is used, where the first Sunday of the year starts the
+first week.  If it is Monday then the ISO 8601 standard week numbering
 is used, where the first Thursday of the year is in week number 1.
 .SH COLORS
-Implicit coloring can be disabled as follows:
+Implicit coloring (highlighting) can be disabled as follows:
 .RS
 
 .br
@@ -158,14 +205,9 @@ for more details about colorization configuration.
 .SH BUGS
 .PP
 .RB The\  \-\-1752-reform
-option 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 reform, 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), including its introduction by Pope Gregory XIII
-in October 1582, are ignored. The Gregorian calendar is a refinement to the
-Julian calendar improving its synchronization with solar cycles.
+option uses 3 Sept 1752 as the date of the Gregorian calendar reform -- that is
+when it happened in Britain.  The historical reform  dates for the other locales,
+including its introduction in October 1582, are ignored.
 .PP
 Alternative calendars, such as the Umm al-Qura, the Solar Hijri, the Ge'ez,
 or the lunisolar Hindu, are not supported.
diff --git a/misc-utils/cal.c b/misc-utils/cal.c
index cf05ecda3..df0568c56 100644
--- a/misc-utils/cal.c
+++ b/misc-utils/cal.c
@@ -1024,7 +1024,7 @@ static void __attribute__((__noreturn__)) usage(void)
 	FILE *out = stdout;
 	fputs(USAGE_HEADER, out);
 	fprintf(out, _(" %s [options] [[[day] month] year]\n"), program_invocation_short_name);
-	fprintf(out, _(" %s [options] <timestamp|monthname>\n"), program_invocation_short_name);
+	fprintf(out, _(" %s [options] [timestamp|month_name]\n"), program_invocation_short_name);
 
 	fputs(USAGE_SEPARATOR, out);
 	fputs(_("Display a calendar, or some part of it.\n"), out);
@@ -1037,12 +1037,12 @@ static void __attribute__((__noreturn__)) usage(void)
 	fputs(_(" -S, --span            span the date when displaying multiple months\n"), out);
 	fputs(_(" -s, --sunday          Sunday as first day of week\n"), out);
 	fputs(_(" -m, --monday          Monday as first day of week\n"), out);
-	fputs(_(" -j, --julian          output Julian dates\n"), out);
+	fputs(_(" -j, --julian          use day-of-year for all calendar types\n"), out);
 	fputs(_(" -y, --year            show the whole year\n"), out);
 	fputs(_(" -Y, --twelve          show the next twelve months\n"), out);
 	fputs(_(" -w, --week[=<num>]    show US or ISO-8601 week numbers\n"), out);
 	fputs(_("     --1752-reform     use Chesterfield's Act format\n"), out);
-	fputs(_("     --color[=<when>]  colorize messages (auto, always or never)\n"), out);
+	fputs(_("     --color[=<when>]  date highlighting (auto, always or never)\n"), out);
 	fprintf(out,
 	        "                         %s\n", USAGE_COLORS_DEFAULT);
 

[v3 PATCH 04/11] cal: rename --julian to --ordinal

[J William Piggott]

Using --julian for ordinal output was confusing.
Also --julian is to be repurposed for Julian Calendar output.

Signed-off-by: J William Piggott <elseifthen@gmx.com>
---
 Documentation/deprecated.txt |  6 ++++++
 misc-utils/cal.1             | 16 +++++++---------
 misc-utils/cal.c             | 41 ++++++++++++++++++++++++-----------------
 3 files changed, 37 insertions(+), 26 deletions(-)

diff --git a/Documentation/deprecated.txt b/Documentation/deprecated.txt
index 34ea698da..d79fd2c80 100644
--- a/Documentation/deprecated.txt
+++ b/Documentation/deprecated.txt
@@ -2,6 +2,12 @@ The following is a list of commands or features that are deprecated.  All
 deprecated utils are in maintenance mode and we keep them in source tree for
 backward compatibility only.
 
+what:  cal --julian
+why:   renamed to --ordinal
+since: v2.32
+
+--------------------------
+
 what:  column --columns
 why:   renamed to --output-width
 since: v2.30
diff --git a/misc-utils/cal.1 b/misc-utils/cal.1
index 7e917886c..afd3bdc5f 100644
--- a/misc-utils/cal.1
+++ b/misc-utils/cal.1
@@ -104,15 +104,13 @@ Display Sunday as the first day of the week.
 Display Monday as the first day of the week.
 .TP
 \fB\-j\fR, \fB\-\-julian\fR
-Use day-of-year numbering for all calendar types.  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 Gregorian
-epoch option
-.BR \%\-\-1752-reform .
-Sometimes Gregorian calendars using ordinal dates are referred to as Julian
-calendars.  This can be confusing because there are many date related
-conventions that use Julian in their name: (ordinal) julian date, julian
-(calendar) date, (astronomical) julian date, (modified) julian date, and more.
+.RB Use\  \-\-ordinal .
+.RB The\  \%\-\-julian\  option
+has been deprecated and may be repurposed or removed in a future release.
+.TP
+.B \-\-ordinal
+Display day-of-year numbering for all calendar types.  Ordinal days range from
+1 to 366.
 .TP
 \fB\-y\fR, \fB\-\-year\fR
 Display a calendar for the whole year.
diff --git a/misc-utils/cal.c b/misc-utils/cal.c
index df0568c56..0990f5199 100644
--- a/misc-utils/cal.c
+++ b/misc-utils/cal.c
@@ -216,7 +216,7 @@ struct cal_control {
 	size_t week_width;		/* 7 * day_width + possible week num */
 	int gutter_width;		/* spaces in between horizontal month outputs */
 	struct cal_request req;		/* the times user is interested */
-	unsigned int	julian:1,	/* julian output */
+	unsigned int	ordinal:1,	/* ordinal output */
 			header_year:1,	/* print year number */
 			header_hint:1;	/* does month name + year need two lines to fit */
 };
@@ -270,7 +270,8 @@ int main(int argc, char **argv)
 
 	enum {
 		OPT_1752_REFORM = CHAR_MAX + 1,
-		OPT_COLOR
+		OPT_COLOR,
+		OPT_ORDINAL
 	};
 
 	static const struct option longopts[] = {
@@ -284,6 +285,7 @@ int main(int argc, char **argv)
 		{"year", no_argument, NULL, 'y'},
 		{"week", optional_argument, NULL, 'w'},
 		{"color", optional_argument, NULL, OPT_COLOR},
+		{"ordinal", no_argument, NULL, OPT_ORDINAL},
 		{"1752-reform", no_argument, NULL, OPT_1752_REFORM},
 		{"version", no_argument, NULL, 'V'},
 		{"twelve", no_argument, NULL, 'Y'},
@@ -366,7 +368,11 @@ int main(int argc, char **argv)
 			ctl.weekstart = MONDAY;
 			break;
 		case 'j':
-			ctl.julian = 1;
+			errx(EXIT_FAILURE,
+			    _("use --ordinal, --julian has been deprecated."));
+			break;
+		case OPT_ORDINAL:
+			ctl.ordinal = 1;
 			ctl.day_width = DAY_LEN + 1;
 			break;
 		case 'y':
@@ -530,7 +536,7 @@ int main(int argc, char **argv)
 	}
 
 	if (ctl.num_months > 1 && ctl.months_in_row == 0)
-		ctl.months_in_row = ctl.julian ? MONTHS_IN_YEAR_ROW - 1 :
+		ctl.months_in_row = ctl.ordinal ? MONTHS_IN_YEAR_ROW - 1 :
 						 MONTHS_IN_YEAR_ROW;
 	else if (!ctl.months_in_row)
 		ctl.months_in_row = 1;
@@ -634,7 +640,7 @@ static void cal_fill_month(struct cal_month *month, const struct cal_control *ct
 	int month_days;
 	int i, j, weeklines = 0;
 
-	if (ctl->julian)
+	if (ctl->ordinal)
 		j = day_in_year(ctl, 1, month->month, month->year);
 	else
 		j = 1;
@@ -710,7 +716,7 @@ static void cal_output_header(struct cal_month *month, const struct cal_control
 	my_putstring("\n");
 	for (i = month; i; i = i->next) {
 		if (ctl->weektype) {
-			if (ctl->julian)
+			if (ctl->ordinal)
 				sprintf(out, "%*s%s", (int)ctl->day_width - 1, "", day_headings);
 			else
 				sprintf(out, "%*s%s", (int)ctl->day_width, "", day_headings);
@@ -737,7 +743,7 @@ static void cal_output_months(struct cal_month *month, const struct cal_control
 			/* Determine the day that should be highlighted. */
 			reqday = 0;
 			if (i->month == ctl->req.month && i->year == ctl->req.year) {
-				if (ctl->julian)
+				if (ctl->ordinal)
 					reqday = ctl->req.day;
 				else
 					reqday = ctl->req.day + 1 -
@@ -766,9 +772,12 @@ static void cal_output_months(struct cal_month *month, const struct cal_control
 			     d < DAYS_IN_WEEK * week_line + DAYS_IN_WEEK; d++) {
 				if (0 < i->days[d]) {
 					if (reqday == i->days[d])
-						sprintf(out, "%*s%s%*d%s", skip - (ctl->julian ? 3 : 2),
-						       "", Senter, (ctl->julian ? 3 : 2),
-						       i->days[d], Sexit);
+						sprintf(out, "%*s%s%*d%s", skip
+							- (ctl->ordinal
+							   ? 3 : 2),
+							"", Senter,
+							(ctl->ordinal ? 3 : 2),
+							i->days[d], Sexit);
 					else
 						sprintf(out, "%*d", skip, i->days[d]);
 				} else
@@ -842,8 +851,8 @@ static void yearly(const struct cal_control *ctl)
 	char out[FMT_ST_CHARS];
 	int year_width = 0;
 
-	year_width += (ctl->week_width + 1) * (ctl->julian ? 2 : 3);
-	if (ctl->julian)
+	year_width += (ctl->week_width + 1) * (ctl->ordinal ? 2 : 3);
+	if (ctl->ordinal)
 		year_width--;
 
 	if (ctl->header_year) {
@@ -927,7 +936,7 @@ static int day_in_week(const struct cal_control *ctl, int day,
  * week_number
  *      return the week number of a given date, 1..54.
  *      Supports ISO-8601 and North American modes.
- *      Day may be given as Julian day of the year mode, in which
+ *      Day may be given as ordinal day, in which
  *      case the month is disregarded entirely.
  */
 static int week_number(int day, int month, int32_t year, const struct cal_control *ctl)
@@ -943,9 +952,7 @@ static int week_number(int day, int month, int32_t year, const struct cal_contro
 		 * more than 52 weeks, */
 		fday = wday + 6;
 	}
-	/* For julian dates the month can be set to 1, the global julian
-	 * variable cannot be relied upon here, because we may recurse
-	 * internally for 31.12. which would not work. */
+	/* For ordinal dates the month can be set to 1 */
 	if (day > DAYS_IN_MONTH)
 		month = JANUARY;
 
@@ -1037,7 +1044,7 @@ static void __attribute__((__noreturn__)) usage(void)
 	fputs(_(" -S, --span            span the date when displaying multiple months\n"), out);
 	fputs(_(" -s, --sunday          Sunday as first day of week\n"), out);
 	fputs(_(" -m, --monday          Monday as first day of week\n"), out);
-	fputs(_(" -j, --julian          use day-of-year for all calendar types\n"), out);
+	fputs(_("     --ordinal         use day-of-year for all calendar types\n"), out);
 	fputs(_(" -y, --year            show the whole year\n"), out);
 	fputs(_(" -Y, --twelve          show the next twelve months\n"), out);
 	fputs(_(" -w, --week[=<num>]    show US or ISO-8601 week numbers\n"), out);

[v3 PATCH 05/11] cal: add private --caesar option

[J William Piggott]

Add a private option named --caesar that will display the
Julian Calendar system exclusively.

After an appropriate mourning period for deprecating --julian
in favor of --ordinal, the private --caesar can be renamed to
-j, --julian and made public.

Signed-off-by: J William Piggott <elseifthen@gmx.com>
---
 misc-utils/cal.1 | 11 +++++++++++
 misc-utils/cal.c | 19 ++++++++++++++-----
 2 files changed, 25 insertions(+), 5 deletions(-)

diff --git a/misc-utils/cal.1 b/misc-utils/cal.1
index afd3bdc5f..17439d2f9 100644
--- a/misc-utils/cal.1
+++ b/misc-utils/cal.1
@@ -90,6 +90,17 @@ Display three months spanning the date.
 Display calendars based upon the Chesterfield's Act.
 This means that dates previous to 3 Sept 1752 will be Julian calendar dates.
 .RB See \ BUGS \ below.
+.\"
+.\" FIXME Dec 25 2017 - after an appropriate mourning period for deprecating
+.\" --julian in favor of --ordinal, the private --caesar will be renamed
+.\" --julian and made public.  Un-comment this section and delete the old
+.\" Julian option description.  Also update the DESCRIPTION section accordingly.
+.\"
+.\" .TP
+.\" .BR \-j ,\ \-\-julian
+.\" Display the Julian calendar system only.
+.\" Note: the old functionality for this option name is now called
+.\" .BR \-\-ordinal .
 .TP
 \fB\-n , \-\-months\fR \fInumber\fR
 Display \fInumber\fR of months, starting from the month containing the date.
diff --git a/misc-utils/cal.c b/misc-utils/cal.c
index 0990f5199..2f0a6be16 100644
--- a/misc-utils/cal.c
+++ b/misc-utils/cal.c
@@ -267,9 +267,14 @@ int main(int argc, char **argv)
 		.req.day = 0,
 		.req.month = 0
 	};
-
+	/*
+	 * FIXME Dec 25 2017 - after an appropriate mourning period for
+	 * deprecating --julian in favor of --ordinal, the private --caesar
+	 * will be renamed -j, --julian and made public.
+	 */
 	enum {
 		OPT_1752_REFORM = CHAR_MAX + 1,
+		OPT_CAESAR,
 		OPT_COLOR,
 		OPT_ORDINAL
 	};
@@ -286,6 +291,7 @@ int main(int argc, char **argv)
 		{"week", optional_argument, NULL, 'w'},
 		{"color", optional_argument, NULL, OPT_COLOR},
 		{"ordinal", no_argument, NULL, OPT_ORDINAL},
+		{"caesar", no_argument, NULL, OPT_CAESAR},
 		{"1752-reform", no_argument, NULL, OPT_1752_REFORM},
 		{"version", no_argument, NULL, 'V'},
 		{"twelve", no_argument, NULL, 'Y'},
@@ -406,6 +412,9 @@ int main(int argc, char **argv)
 		case OPT_1752_REFORM:
 			ctl.reform_year = 1752;
 			break;
+		case OPT_CAESAR:
+			ctl.reform_year = INT32_MAX;
+			break;
 		case 'V':
 			printf(UTIL_LINUX_VERSION);
 			return EXIT_SUCCESS;
@@ -921,14 +930,14 @@ static int day_in_week(const struct cal_control *ctl, int day,
 	if (ctl->reform_year < year
 	    || (year == ctl->reform_year && REFORM_MONTH < month)
 	    || (year == ctl->reform_year && month == REFORM_MONTH && 13 < day)) {
-		int64_t long_year = year;
-		return (long_year + (year / 4) - (year / 100) + (year / 400) +
-			reform[month - 1] + day) % DAYS_IN_WEEK;
+		return ((int64_t) year + (year / 4) - (year / 100) + (year / 400)
+			+ reform[month - 1] + day) % DAYS_IN_WEEK;
 	}
 	if (year < ctl->reform_year
 	    || (year == ctl->reform_year && month < REFORM_MONTH)
 	    || (year == ctl->reform_year && month == REFORM_MONTH && day < 3))
-		return (year + year / 4 + old[month - 1] + day) % DAYS_IN_WEEK;
+		return ((int64_t) year + year / 4 + old[month - 1] + day)
+			% DAYS_IN_WEEK;
 	return NONEDAY;
 }
 

[v3 PATCH 06/11] cal: make -w accept its optional argument

[J William Piggott]

This was removed in commit af7c483 due a mailing list comment:

https://marc.info/?l=util-linux-ng&m=138116560906549&w=2
 It's generally best to avoid optional args on short args,
 as in this case -w3 is ambiguous and -wj is problematic.
 So I'd instead support an interface like -w,--week[=NUM]

cal -wj
cal: invalid week argument: 'j'

cal -w3
      January 2018
   Su Mo Tu We Th Fr Sa
 1     1  2  3  4  5  6
 2  7  8  9 10 11 12 13
 3 14 15 16 17 18 19 20
 4 21 22 23 24 25 26 27
 5 28 29 30 31

That should be an expected result for those commands.

Util-linux has many commands with optional args for short options:
ipcrm, swapon, lscpu, nsenter, dmesg, script, cfdisk, fdisk, hexdump

It seems unexpected to have an argument for long options only. I found
this because I tried to pass an argument to -w.

Signed-off-by: J William Piggott <elseifthen@gmx.com>
---
 misc-utils/cal.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/misc-utils/cal.c b/misc-utils/cal.c
index 2f0a6be16..02283bc04 100644
--- a/misc-utils/cal.c
+++ b/misc-utils/cal.c
@@ -354,7 +354,7 @@ int main(int argc, char **argv)
 		ctl.weekstart = (wfd + *nl_langinfo(_NL_TIME_FIRST_WEEKDAY) - 1) % DAYS_IN_WEEK;
 	}
 #endif
-	while ((ch = getopt_long(argc, argv, "13mjn:sSywYVh", longopts, NULL)) != -1) {
+	while ((ch = getopt_long(argc, argv, "13mjn:sSyw::YVh", longopts, NULL)) != -1) {
 
 		err_exclusive_options(ch, longopts, excl, excl_st);
 

[v3 PATCH 07/11] cal: update mutually exclusive options

[J William Piggott]

Signed-off-by: J William Piggott <elseifthen@gmx.com>
---
 misc-utils/cal.c | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/misc-utils/cal.c b/misc-utils/cal.c
index 02283bc04..00c00ebc0 100644
--- a/misc-utils/cal.c
+++ b/misc-utils/cal.c
@@ -300,7 +300,9 @@ int main(int argc, char **argv)
 	};
 
 	static const ul_excl_t excl[] = {       /* rows and cols in ASCII order */
-		{ 'Y','n','y' },
+		{ '1', '3', 'Y', 'n', 'y' },
+		{ 'm', 's' },
+		{ OPT_1752_REFORM, OPT_CAESAR },
 		{ 0 }
 	};
 	int excl_st[ARRAY_SIZE(excl)] = UL_EXCL_STATUS_INIT;

[v3 PATCH 08/11] cal: add short versions of new options

[J William Piggott]

Also, the project uses 'L' for --color so that
was added.

Signed-off-by: J William Piggott <elseifthen@gmx.com>
---
 misc-utils/cal.1 |  6 +++---
 misc-utils/cal.c | 28 +++++++++++++---------------
 2 files changed, 16 insertions(+), 18 deletions(-)

diff --git a/misc-utils/cal.1 b/misc-utils/cal.1
index 17439d2f9..718a38c98 100644
--- a/misc-utils/cal.1
+++ b/misc-utils/cal.1
@@ -86,7 +86,7 @@ Display single month output (default).
 \fB\-3\fR, \fB\-\-three\fR
 Display three months spanning the date.
 .TP
-.B \-\-1752-reform
+.BR \-r ,\  \-\-1752-reform
 Display calendars based upon the Chesterfield's Act.
 This means that dates previous to 3 Sept 1752 will be Julian calendar dates.
 .RB See \ BUGS \ below.
@@ -119,7 +119,7 @@ Display Monday as the first day of the week.
 .RB The\  \%\-\-julian\  option
 has been deprecated and may be repurposed or removed in a future release.
 .TP
-.B \-\-ordinal
+.BR \-o ,\  \-\-ordinal
 Display day-of-year numbering for all calendar types.  Ordinal days range from
 1 to 366.
 .TP
@@ -140,7 +140,7 @@ will be highlighted only if its month is displayed.  For example, if the
 option is used.
 .RB See\  \-\-color.
 .TP
-\fB\-\-color\fR[=\fIwhen\fR]
+\fB\-L\fR, \fB\-\-color\fR[=\fIwhen\fR]
 Control day/week highlighting.  The optional argument \fIwhen\fP can be
 \fBauto\fR, \fBnever\fR or \fBalways\fR.  If the \fIwhen\fR argument is
 omitted, it defaults to \fBauto\fR.  Auto means it is on if the output is to a
diff --git a/misc-utils/cal.c b/misc-utils/cal.c
index 00c00ebc0..6f7dadfac 100644
--- a/misc-utils/cal.c
+++ b/misc-utils/cal.c
@@ -273,10 +273,7 @@ int main(int argc, char **argv)
 	 * will be renamed -j, --julian and made public.
 	 */
 	enum {
-		OPT_1752_REFORM = CHAR_MAX + 1,
-		OPT_CAESAR,
-		OPT_COLOR,
-		OPT_ORDINAL
+		OPT_CAESAR = CHAR_MAX + 1
 	};
 
 	static const struct option longopts[] = {
@@ -289,10 +286,10 @@ int main(int argc, char **argv)
 		{"span", no_argument, NULL, 'S'},
 		{"year", no_argument, NULL, 'y'},
 		{"week", optional_argument, NULL, 'w'},
-		{"color", optional_argument, NULL, OPT_COLOR},
-		{"ordinal", no_argument, NULL, OPT_ORDINAL},
+		{"color", optional_argument, NULL, 'L'},
+		{"ordinal", no_argument, NULL, 'o'},
 		{"caesar", no_argument, NULL, OPT_CAESAR},
-		{"1752-reform", no_argument, NULL, OPT_1752_REFORM},
+		{"1752-reform", no_argument, NULL, 'r'},
 		{"version", no_argument, NULL, 'V'},
 		{"twelve", no_argument, NULL, 'Y'},
 		{"help", no_argument, NULL, 'h'},
@@ -302,7 +299,7 @@ int main(int argc, char **argv)
 	static const ul_excl_t excl[] = {       /* rows and cols in ASCII order */
 		{ '1', '3', 'Y', 'n', 'y' },
 		{ 'm', 's' },
-		{ OPT_1752_REFORM, OPT_CAESAR },
+		{ 'r', OPT_CAESAR },
 		{ 0 }
 	};
 	int excl_st[ARRAY_SIZE(excl)] = UL_EXCL_STATUS_INIT;
@@ -356,7 +353,8 @@ int main(int argc, char **argv)
 		ctl.weekstart = (wfd + *nl_langinfo(_NL_TIME_FIRST_WEEKDAY) - 1) % DAYS_IN_WEEK;
 	}
 #endif
-	while ((ch = getopt_long(argc, argv, "13mjn:sSyw::YVh", longopts, NULL)) != -1) {
+	while ((ch = getopt_long(argc, argv, "13jL::mn:orsSyw::YVh",
+				 longopts, NULL)) != -1) {
 
 		err_exclusive_options(ch, longopts, excl, excl_st);
 
@@ -379,7 +377,7 @@ int main(int argc, char **argv)
 			errx(EXIT_FAILURE,
 			    _("use --ordinal, --julian has been deprecated."));
 			break;
-		case OPT_ORDINAL:
+		case 'o':
 			ctl.ordinal = 1;
 			ctl.day_width = DAY_LEN + 1;
 			break;
@@ -405,13 +403,13 @@ int main(int argc, char **argv)
 			}
 			ctl.weektype = WEEK_NUM_US;	/* default per weekstart */
 			break;
-		case OPT_COLOR:
+		case 'L':
 			ctl.colormode = UL_COLORMODE_AUTO;
 			if (optarg)
 				ctl.colormode = colormode_or_err(optarg,
 						_("unsupported color mode"));
 			break;
-		case OPT_1752_REFORM:
+		case 'r':
 			ctl.reform_year = 1752;
 			break;
 		case OPT_CAESAR:
@@ -1055,12 +1053,12 @@ static void __attribute__((__noreturn__)) usage(void)
 	fputs(_(" -S, --span            span the date when displaying multiple months\n"), out);
 	fputs(_(" -s, --sunday          Sunday as first day of week\n"), out);
 	fputs(_(" -m, --monday          Monday as first day of week\n"), out);
-	fputs(_("     --ordinal         use day-of-year for all calendar types\n"), out);
+	fputs(_(" -o  --ordinal         use day-of-year for all calendar types\n"), out);
 	fputs(_(" -y, --year            show the whole year\n"), out);
 	fputs(_(" -Y, --twelve          show the next twelve months\n"), out);
 	fputs(_(" -w, --week[=<num>]    show US or ISO-8601 week numbers\n"), out);
-	fputs(_("     --1752-reform     use Chesterfield's Act format\n"), out);
-	fputs(_("     --color[=<when>]  date highlighting (auto, always or never)\n"), out);
+	fputs(_(" -r  --1752-reform     use Chesterfield's Act format\n"), out);
+	fputs(_(" -L  --color[=<when>]  date highlighting (auto, always or never)\n"), out);
 	fprintf(out,
 	        "                         %s\n", USAGE_COLORS_DEFAULT);
 

[v3 PATCH 09/11] cal: remove the non-functional options

[J William Piggott]

--one and --sunday are the default behavior making
the options no-op.

Signed-off-by: J William Piggott <elseifthen@gmx.com>
---
 misc-utils/cal.1 | 24 +++++++++---------------
 misc-utils/cal.c | 19 ++++---------------
 2 files changed, 13 insertions(+), 30 deletions(-)

diff --git a/misc-utils/cal.1 b/misc-utils/cal.1
index 718a38c98..23e21c3a5 100644
--- a/misc-utils/cal.1
+++ b/misc-utils/cal.1
@@ -80,9 +80,6 @@ Julian calendar dates.
 
 .SH OPTIONS
 .TP
-\fB\-1\fR, \fB\-\-one\fR
-Display single month output (default).
-.TP
 \fB\-3\fR, \fB\-\-three\fR
 Display three months spanning the date.
 .TP
@@ -108,11 +105,8 @@ Display \fInumber\fR of months, starting from the month containing the date.
 \fB\-S, \fB\-\-span\fR
 Span the date when displaying multiple months.
 .TP
-\fB\-s\fR, \fB\-\-sunday\fR
-Display Sunday as the first day of the week.
-.TP
 \fB\-m\fR, \fB\-\-monday\fR
-Display Monday as the first day of the week.
+Display Monday as the first day of the week (Sunday is default).
 .TP
 \fB\-j\fR, \fB\-\-julian\fR
 .RB Use\  \-\-ordinal .
@@ -189,16 +183,16 @@ highlighted.
 .TP
 If no parameters are specified, the current month's calendar is displayed.
 .SH NOTES
-A year starts on January 1.  The first day of the week is determined by the
-locale or the
-.BR \-\-sunday \ and \ \-\-monday \ options.
+A year starts on January 1.  The first day of the week is determined either by
+the locale, the
+.BR \-\-monday \ option,
+or defaults to Sunday.
 .PP
 The week numbering depends on the choice of the first day of the week.  If it
-is Sunday
-(the default) then the customary North
-American numbering is used, where the first Sunday of the year starts the
-first week.  If it is Monday then the ISO 8601 standard week numbering
-is used, where the first Thursday of the year is in week number 1.
+is Sunday (the default) then the customary North American numbering is used,
+where the first Sunday of the year starts the first week.  If it is Monday then
+the ISO 8601 standard week numbering is used, where the first Thursday of the
+year is in week number 1.
 .SH COLORS
 Implicit coloring (highlighting) can be disabled as follows:
 .RS
diff --git a/misc-utils/cal.c b/misc-utils/cal.c
index 6f7dadfac..0756f922f 100644
--- a/misc-utils/cal.c
+++ b/misc-utils/cal.c
@@ -257,8 +257,8 @@ int main(int argc, char **argv)
 
 	static struct cal_control ctl = {
 		.reform_year = -1,		/* def. proleptic Gregorian */
-		.weekstart = SUNDAY,
-		.num_months = 1,		/* default is "cal -1" */
+		.weekstart = SUNDAY,		/* default */
+		.num_months = 1,		/* default */
 		.span_months = 0,
 		.colormode = UL_COLORMODE_UNDEF,
 		.weektype = WEEK_NUM_DISABLED,
@@ -277,9 +277,7 @@ int main(int argc, char **argv)
 	};
 
 	static const struct option longopts[] = {
-		{"one", no_argument, NULL, '1'},
 		{"three", no_argument, NULL, '3'},
-		{"sunday", no_argument, NULL, 's'},
 		{"monday", no_argument, NULL, 'm'},
 		{"julian", no_argument, NULL, 'j'},
 		{"months", required_argument, NULL, 'n'},
@@ -297,8 +295,7 @@ int main(int argc, char **argv)
 	};
 
 	static const ul_excl_t excl[] = {       /* rows and cols in ASCII order */
-		{ '1', '3', 'Y', 'n', 'y' },
-		{ 'm', 's' },
+		{ '3', 'Y', 'n', 'y' },
 		{ 'r', OPT_CAESAR },
 		{ 0 }
 	};
@@ -353,23 +350,17 @@ int main(int argc, char **argv)
 		ctl.weekstart = (wfd + *nl_langinfo(_NL_TIME_FIRST_WEEKDAY) - 1) % DAYS_IN_WEEK;
 	}
 #endif
-	while ((ch = getopt_long(argc, argv, "13jL::mn:orsSyw::YVh",
+	while ((ch = getopt_long(argc, argv, "3jL::mn:orSyw::YVh",
 				 longopts, NULL)) != -1) {
 
 		err_exclusive_options(ch, longopts, excl, excl_st);
 
 		switch(ch) {
-		case '1':
-			/* default */
-			break;
 		case '3':
 			ctl.num_months = 3;
 			ctl.span_months = 1;
 			ctl.months_in_row = 3;
 			break;
-		case 's':
-			ctl.weekstart = SUNDAY;		/* default */
-			break;
 		case 'm':
 			ctl.weekstart = MONDAY;
 			break;
@@ -1047,11 +1038,9 @@ static void __attribute__((__noreturn__)) usage(void)
 	fputs(_("Without any arguments, display the current month.\n"), out);
 
 	fputs(USAGE_OPTIONS, out);
-	fputs(_(" -1, --one             show only a single month (default)\n"), out);
 	fputs(_(" -3, --three           show three months spanning the date\n"), out);
 	fputs(_(" -n, --months <num>    show num months starting with date's month\n"), out);
 	fputs(_(" -S, --span            span the date when displaying multiple months\n"), out);
-	fputs(_(" -s, --sunday          Sunday as first day of week\n"), out);
 	fputs(_(" -m, --monday          Monday as first day of week\n"), out);
 	fputs(_(" -o  --ordinal         use day-of-year for all calendar types\n"), out);
 	fputs(_(" -y, --year            show the whole year\n"), out);

[v3 PATCH 10/11] cal: fix first week calculation

[J William Piggott]

Commit efafeaf set 1 Jan as week 1, but the change
was missed in week_to_day() and in the man page.

Before
cal --week=40 1752
      October 1752
   Su Mo Tu We Th Fr Sa
41  1  2  3  4  5  6  7
42  8  9 10 11 12 13 14
43 15 16 17 18 19 20 21
44 22 23 24 25 26 27 28
45 29 30 31

Patched
cal --week=40 1752
     September 1752
   Su Mo Tu We Th Fr Sa
36                 1  2
37  3  4  5  6  7  8  9
38 10 11 12 13 14 15 16
39 17 18 19 20 21 22 23
40 24 25 26 27 28 29 30

Signed-off-by: J William Piggott <elseifthen@gmx.com>
---
 misc-utils/cal.1 | 5 ++---
 misc-utils/cal.c | 2 +-
 2 files changed, 3 insertions(+), 4 deletions(-)

diff --git a/misc-utils/cal.1 b/misc-utils/cal.1
index 23e21c3a5..14125bafc 100644
--- a/misc-utils/cal.1
+++ b/misc-utils/cal.1
@@ -190,9 +190,8 @@ or defaults to Sunday.
 .PP
 The week numbering depends on the choice of the first day of the week.  If it
 is Sunday (the default) then the customary North American numbering is used,
-where the first Sunday of the year starts the first week.  If it is Monday then
-the ISO 8601 standard week numbering is used, where the first Thursday of the
-year is in week number 1.
+where 1 January is in week number 1.  If it is Monday then the ISO 8601
+standard week numbering is used, where the first Thursday is in week number 1.
 .SH COLORS
 Implicit coloring (highlighting) can be disabled as follows:
 .RS
diff --git a/misc-utils/cal.c b/misc-utils/cal.c
index 0756f922f..2a24dad26 100644
--- a/misc-utils/cal.c
+++ b/misc-utils/cal.c
@@ -994,7 +994,7 @@ static int week_to_day(const struct cal_control *ctl)
 	if (ctl->weektype & WEEK_NUM_ISO)
 		yday -= (wday >= FRIDAY ? -2 : 5);
 	else
-		yday -= (wday == SUNDAY ? 6 : -1);	/* WEEK_NUM_US */
+		yday -= 6;	/* WEEK_NUM_US */
 	if (yday <= 0)
 		return 1;
 

[v3 PATCH 11/11] cal: fix week calculations for --1752-reform

[J William Piggott]

Before
./cal --week=39 --1752-reform 1752
     September 1752
   Su Mo Tu We Th Fr Sa
36        1  2 14 15 16
37 17 18 19 20 21 22 23
38 24 25 26 27 28 29 30

Patched
./cal --week=39 --1752-reform 1752
      October 1752
   Su Mo Tu We Th Fr Sa
39  1  2  3  4  5  6  7
40  8  9 10 11 12 13 14
41 15 16 17 18 19 20 21
42 22 23 24 25 26 27 28
43 29 30 31

Signed-off-by: J William Piggott <elseifthen@gmx.com>
---
 misc-utils/cal.c | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/misc-utils/cal.c b/misc-utils/cal.c
index 2a24dad26..18f58e548 100644
--- a/misc-utils/cal.c
+++ b/misc-utils/cal.c
@@ -991,6 +991,9 @@ static int week_to_day(const struct cal_control *ctl)
 	wday = day_in_week(ctl, 1, JANUARY, ctl->req.year);
 	yday = ctl->req.week * DAYS_IN_WEEK - wday;
 
+	if (ctl->req.year == ctl->reform_year && yday >= YDAY_AFTER_MISSING)
+		yday += NUMBER_MISSING_DAYS;
+
 	if (ctl->weektype & WEEK_NUM_ISO)
 		yday -= (wday >= FRIDAY ? -2 : 5);
 	else

Re: [v3 PATCH 00/11] Pull Request - changelog

[Karel Zak]

On Tue, Jan 02, 2018 at 09:53:18AM -0500, J William Piggott wrote:
> Having not received any reply

I had Christmas vacation ;-) I'll review all the patches later this
week.

    Karel


-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com

Re: [v3 PATCH 00/11] Pull Request - changelog

[Karel Zak]

On Tue, Jan 02, 2018 at 09:53:18AM -0500, J William Piggott wrote:
> Having not received any reply, I went ahead with the
> implementation, with one change involving Karel's original
> request for volunteers. Specifically, the first and last bullet
> points; which where:
> 
> * keep the current default "British Empire" behavior (Gregorian since
>   September 1752)
> 
> * later (after warning in release notes) we can make --gregorian as
>   the default
> 
> During implementation I considered these issues:
> 
> * to do that we'd be creating two new options --iso, and an
>   alias --gregorian; these would become non-functional once
>   they were made the default. Just like the current situation
>   with --one and --sunday.

It's not so unusual to have command line options for default behavior,
and it's good idea to use these options for example in scripts to be
independent on the current defaults.

> * this change is unlikely to affect downstream maintainers
> 
> * end users are the ones that may be caught out by it
> 
> * a release note warning that some future version of cal(1)
>   will change the default output is unlikely to reach the end
>   users.

I have no clue how many users care and read our ReleaseNotes, but
important is that they have opportunity to do that and they have
always time to adopt to changes. This is how I promised that this 
project will be maintained. 

> Indirectly, the current tests are broken. I think this
> supports some of the changes in this patch set:
> 
> The tests author seemed to believe that the -1 and -s options
> actually do something, despite the 'expected' output showing
> otherwise. While testing this patch set I thought the same
> thing; I tried to figure out what these two options do; which
> is nothing. I think this is good evidence to support removing
> them.

It's bug that -1/--one does nothing and this bug should be fixed. The
-s seems to set ctl->weekstart (and it would be probably more robust
to compare it with SUNDAY rather than with zero in code).

> The tests author also seems to believe that the -j option
> switches from the Gregorian calendar system to the Julian
> calendar system. Making comments to that affect and using it
> in tests involving the year 1752; a year which uses both
> calendar systems. I think this is good evidence to support
> renaming --julian to --ordinal.
> 
> If developers for the project are being confused by these
> options, than what chance do end users have? So that's my case
> for making these changes.

This is good point. I think the problem is that nowhere in the man
page has been described all the history and differences between
calendars.

> Also while pounding on cal(1), to see if these patches broke
> anything, I found a few other issues and fixed them as well.
> The man page was quite sparse, for example having no explanation
> for the -w argument, so rewrote much of it.

Thanks.

> v2 to v3 changelog
> * make proleptic Gregorian the default
> * extensive man page updates
> * rename --julian to --ordinal

Yes, this is mess...

> * add private (for now) --caesar option for exclusive Julian calendar

> * allow -w to accept its argument
> * update mutually exclusive options
> * add short versions for the new options
> * remove non-functional options
> * fix broken week calculations

Thanks!

> 
> v1 to v2 changelog
>  * fix typo in v1
>  * move REFORMATION_YEAR to the control struct
>  * add more about the --1752-reform option to man page
>  * add a second patch with minor style and wording changes

Thanks. I'll work on cal(1) in next days and use us much as possible
from your patches. 

Thanks for patience, I understand that you want to be a little bit
more aggressive with the changes and do it in the "best way" now, but
I'd like to be a little bit more conservative :-)

    Karel

-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com

Re: [v3 PATCH 00/11] Pull Request - changelog

[J William Piggott]

On 01/08/2018 05:21 AM, Karel Zak wrote:
> On Tue, Jan 02, 2018 at 09:53:18AM -0500, J William Piggott wrote:
>> Having not received any reply, I went ahead with the
>> implementation, with one change involving Karel's original
>> request for volunteers. Specifically, the first and last bullet
>> points; which where:
>>
>> * keep the current default "British Empire" behavior (Gregorian since
>>   September 1752)
>>
>> * later (after warning in release notes) we can make --gregorian as
>>   the default
>>
>> During implementation I considered these issues:
>>
>> * to do that we'd be creating two new options --iso, and an
>>   alias --gregorian; these would become non-functional once
>>   they were made the default. Just like the current situation
>>   with --one and --sunday.
> 
> It's not so unusual to have command line options for default behavior,
> and it's good idea to use these options for example in scripts to be
> independent on the current defaults.
> 

Having options for defaults is required if there is a way to change the
defaults. In this case there is not. If you want to add ~/.calrc and/or
/etc/calrc, then the options would have some meaning; as things stand
they only add confusion, IMO. It might be a nice feature to have a
config file for cal.  For example, I have cal aliased to cal -3.

>> * this change is unlikely to affect downstream maintainers
>>
>> * end users are the ones that may be caught out by it
>>
>> * a release note warning that some future version of cal(1)
>>   will change the default output is unlikely to reach the end
>>   users.
> 
> I have no clue how many users care and read our ReleaseNotes, but
> important is that they have opportunity to do that and they have
> always time to adopt to changes. This is how I promised that this 
> project will be maintained. 

A promise is a promise ;) I really just wanted to avoid adding options
that would later become default and meaningless, but we'd be stuck with
them forever. Seemed like a bad way to go ... to me.

> 
>> Indirectly, the current tests are broken. I think this
>> supports some of the changes in this patch set:
>>
>> The tests author seemed to believe that the -1 and -s options
>> actually do something, despite the 'expected' output showing
>> otherwise. While testing this patch set I thought the same
>> thing; I tried to figure out what these two options do; which
>> is nothing. I think this is good evidence to support removing
>> them.
> 
> It's bug that -1/--one does nothing and this bug should be fixed. The
> -s seems to set ctl->weekstart (and it would be probably more robust
> to compare it with SUNDAY rather than with zero in code).

Right, but since -s and -m; -1, -3, -y, and -Y should be mutually
exclusive, -s and -1 do nothing (unless there exists a calrc).

> 
>> The tests author also seems to believe that the -j option
>> switches from the Gregorian calendar system to the Julian
>> calendar system. Making comments to that affect and using it
>> in tests involving the year 1752; a year which uses both
>> calendar systems. I think this is good evidence to support
>> renaming --julian to --ordinal.
>>
>> If developers for the project are being confused by these
>> options, than what chance do end users have? So that's my case
>> for making these changes.
> 
> This is good point. I think the problem is that nowhere in the man
> page has been described all the history and differences between
> calendars.
  
That, and because someone decided to call Gregorian calendars with
ordinal days, Julian calendars. What were they thinking! I understand
the relationship between ordinal days and Astronomical Julian Days, but
Julian Calendars already existed. Talk about namespace violations. I
have the impression that this problem is beginning to be recognized and
that CS is slowly migrating from julian in favor of ordinal.

>> Also while pounding on cal(1), to see if these patches broke
>> anything, I found a few other issues and fixed them as well.
>> The man page was quite sparse, for example having no explanation
>> for the -w argument, so rewrote much of it.
> 
> Thanks.
> 
>> v2 to v3 changelog
>> * make proleptic Gregorian the default
>> * extensive man page updates
>> * rename --julian to --ordinal
> 
> Yes, this is mess...
>

A mess? Awe, it's not that bad ;) I understand you must keep your
promise with regard to warning before changing the default behavior; but
you think renaming --julian to --ordinal is not good?

>> * add private (for now) --caesar option for exclusive Julian calendar
> 
>> * allow -w to accept its argument
>> * update mutually exclusive options
>> * add short versions for the new options
>> * remove non-functional options
>> * fix broken week calculations
> 
> Thanks!
> 
>>
>> v1 to v2 changelog
>>  * fix typo in v1
>>  * move REFORMATION_YEAR to the control struct
>>  * add more about the --1752-reform option to man page
>>  * add a second patch with minor style and wording changes
> 
> Thanks. I'll work on cal(1) in next days and use us much as possible
> from your patches. 
> 
> Thanks for patience, I understand that you want to be a little bit
> more aggressive with the changes and do it in the "best way" now, but
> I'd like to be a little bit more conservative :-)

It sounds like you have no choice ;)

> 
>     Karel
> 

Re: [v3 PATCH 00/11] Pull Request - changelog

[Ruediger Meier]

On Tuesday 09 January 2018, J William Piggott wrote:
> On 01/08/2018 05:21 AM, Karel Zak wrote:
> > On Tue, Jan 02, 2018 at 09:53:18AM -0500, J William Piggott wrote:
> >> Having not received any reply, I went ahead with the
> >> implementation, with one change involving Karel's original
> >> request for volunteers. Specifically, the first and last bullet
> >> points; which where:
> >>
> >> * keep the current default "British Empire" behavior (Gregorian
> >> since September 1752)
> >>
> >> * later (after warning in release notes) we can make --gregorian
> >> as the default
> >>
> >> During implementation I considered these issues:
> >>
> >> * to do that we'd be creating two new options --iso, and an
> >>   alias --gregorian; these would become non-functional once
> >>   they were made the default. Just like the current situation
> >>   with --one and --sunday.
> >
> > It's not so unusual to have command line options for default
> > behavior, and it's good idea to use these options for example in
> > scripts to be independent on the current defaults.
>
> Having options for defaults is required if there is a way to change
> the defaults. In this case there is not. If you want to add ~/.calrc
> and/or /etc/calrc, then the options would have some meaning; as
> things stand they only add confusion, IMO. It might be a nice feature
> to have a config file for cal.  For example, I have cal aliased to
> cal -3.


> >> * this change is unlikely to affect downstream maintainers
> >>
> >> * end users are the ones that may be caught out by it
> >>
> >> * a release note warning that some future version of cal(1)
> >>   will change the default output is unlikely to reach the end
> >>   users.
> >
> > I have no clue how many users care and read our ReleaseNotes, but
> > important is that they have opportunity to do that and they have
> > always time to adopt to changes. This is how I promised that this
> > project will be maintained.
>
> A promise is a promise ;) I really just wanted to avoid adding
> options that would later become default and meaningless, but we'd be
> stuck with them forever. Seemed like a bad way to go ... to me.
>
> >> Indirectly, the current tests are broken. I think this
> >> supports some of the changes in this patch set:
> >>
> >> The tests author seemed to believe that the -1 and -s options
> >> actually do something, despite the 'expected' output showing
> >> otherwise. While testing this patch set I thought the same
> >> thing; I tried to figure out what these two options do; which
> >> is nothing. I think this is good evidence to support removing
> >> them.
> >
> > It's bug that -1/--one does nothing and this bug should be fixed.
> > The -s seems to set ctl->weekstart (and it would be probably more
> > robust to compare it with SUNDAY rather than with zero in code).
>
> Right, but since -s and -m; -1, -3, -y, and -Y should be mutually
> exclusive, -s and -1 do nothing (unless there exists a calrc).

Of course -1 does something. Last option wins. Real life use case below.

$ alias cal='cal -3'
$ cal -1
    January 2018
Su Mo Tu We Th Fr Sa
    1  2  3  4  5  6
 7  8  9 10 11 12 13
14 15 16 17 18 19 20
21 22 23 24 25 26 27
28 29 30 31


> >> The tests author also seems to believe that the -j option
> >> switches from the Gregorian calendar system to the Julian
> >> calendar system. Making comments to that affect and using it
> >> in tests involving the year 1752; a year which uses both
> >> calendar systems. I think this is good evidence to support
> >> renaming --julian to --ordinal.
> >>
> >> If developers for the project are being confused by these
> >> options, than what chance do end users have? So that's my case
> >> for making these changes.
> >
> > This is good point. I think the problem is that nowhere in the man
> > page has been described all the history and differences between
> > calendars.
>
> That, and because someone decided to call Gregorian calendars with
> ordinal days, Julian calendars. What were they thinking! I understand
> the relationship between ordinal days and Astronomical Julian Days,
> but Julian Calendars already existed. Talk about namespace
> violations. I have the impression that this problem is beginning to
> be recognized and that CS is slowly migrating from julian in favor of
> ordinal.
>
> >> Also while pounding on cal(1), to see if these patches broke
> >> anything, I found a few other issues and fixed them as well.
> >> The man page was quite sparse, for example having no explanation
> >> for the -w argument, so rewrote much of it.
> >
> > Thanks.
> >
> >> v2 to v3 changelog
> >> * make proleptic Gregorian the default
> >> * extensive man page updates
> >> * rename --julian to --ordinal
> >
> > Yes, this is mess...
>
> A mess? Awe, it's not that bad ;) I understand you must keep your
> promise with regard to warning before changing the default behavior;
> but you think renaming --julian to --ordinal is not good?
>
> >> * add private (for now) --caesar option for exclusive Julian
> >> calendar
> >>
> >> * allow -w to accept its argument
> >> * update mutually exclusive options
> >> * add short versions for the new options
> >> * remove non-functional options
> >> * fix broken week calculations
> >
> > Thanks!
> >
> >> v1 to v2 changelog
> >>  * fix typo in v1
> >>  * move REFORMATION_YEAR to the control struct
> >>  * add more about the --1752-reform option to man page
> >>  * add a second patch with minor style and wording changes
> >
> > Thanks. I'll work on cal(1) in next days and use us much as
> > possible from your patches.
> >
> > Thanks for patience, I understand that you want to be a little bit
> > more aggressive with the changes and do it in the "best way" now,
> > but I'd like to be a little bit more conservative :-)
>
> It sounds like you have no choice ;)
>
> >     Karel
>
> --
> To unsubscribe from this list: send the line "unsubscribe util-linux"
> in the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [v3 PATCH 00/11] Pull Request - changelog

[J William Piggott]

On 01/08/2018 05:21 AM, Karel Zak wrote:
> On Tue, Jan 02, 2018 at 09:53:18AM -0500, J William Piggott wrote:
> 
> I have no clue how many users care and read our ReleaseNotes, but
> important is that they have opportunity to do that and they have
> always time to adopt to changes. This is how I promised that this 
> project will be maintained. 

Your response here puzzled me, because I could not remember you ever
making a pre-announcement of this nature before.  For example when
hwclock's default output format was changed in v2.28 it didn't even make
the release highlights, let alone require a pre-change announcement.  I
did a quick grep and could not find a single instance of an advance
notification for this type of change.

> Thanks. I'll work on cal(1) in next days and use us much as possible
> from your patches.

I originally started a branch implemented for an advance notification; I
backported some of my later fixes from the v3 submission to it. The
resulting branch may be more to your liking:
  git@github.com:jwpi/util-linux.git 171225

The current v3 submission's branch is:
  git@github.com:jwpi/util-linux.git 171229

Both branches have an updated commit message for renaming --julian to
--ordinal, expanding on the rational for it:

    cal(1) is unique in that it uses both Julian and Gregorian calendar
    systems.  This causes a name collision with the --julian ordinal day
    option.

    Other commonly distributed code for POSIX-like systems do not share this
    problem because they all use the proleptic Gregorian calendar system
    exclusively; so they can get away with calling ordinal days 'julian' and
    using things like %j for formatting ordinal days.

    For cal(1) this ambiguity is problematic for developers, users,
    and for the implementation itself.

    There are no alternate names for the Julian calendar (system);
    alternates names for (ordinal) Julian calendar are: day-of-year,
    and ordinal. Ordinal being the preferred name:
     https://en.wikipedia.org/wiki/Julian_day#Terminology
     https://en.wikipedia.org/wiki/Ordinal_date

    To implement an exclusive Julian Calendar output for cal(1) it will need
    to use the name Julian, because there are no alternatives. Even for a
    mixed calendar output the dates earlier than the reform epoch need to be
    labeled and referred to as 'Julian'.

    Therefore, the current --julian option needs to be renamed to --ordinal.


While working on cal I discovered more things that are broken. I wanted
to include the fixes in this patch set, but I thought it would be too
much for this round. What I envision as the output to address these new
issues will also need to use the term Julian to represent the calendar
system.

Re: [v3 PATCH 00/11] Pull Request - changelog

[Karel Zak]

On Wed, Jan 10, 2018 at 09:00:23PM -0500, J William Piggott wrote:
> 
> 
> On 01/08/2018 05:21 AM, Karel Zak wrote:
> > On Tue, Jan 02, 2018 at 09:53:18AM -0500, J William Piggott wrote:
> > 
> > I have no clue how many users care and read our ReleaseNotes, but
> > important is that they have opportunity to do that and they have
> > always time to adopt to changes. This is how I promised that this 
> > project will be maintained. 
> 
> Your response here puzzled me, because I could not remember you ever
> making a pre-announcement of this nature before.

2.14  The losetup(8) '-s' option (introduced by util-linux-ng-2.13) is deprecated
2.21  The udev compatible output (-o udev) from blkid(8) is deprecated.
2.25  The "swapon --summary" output format is deprecated ...

... and many warnings about commands (mkfs, tailf, mount, last, ...) and
features (cryptoloop).

The command line options are our API, we don't do such changes often.

I remember only one exception -- sfdisk, after rewrite some obscure
DOS-era options have been removed.

    Karel

-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com

Re: [v3 PATCH 00/11] Pull Request - changelog

[J William Piggott]

On 01/11/2018 04:01 AM, Karel Zak wrote:
> On Wed, Jan 10, 2018 at 09:00:23PM -0500, J William Piggott wrote:
>>
>>
>> On 01/08/2018 05:21 AM, Karel Zak wrote:
>>> On Tue, Jan 02, 2018 at 09:53:18AM -0500, J William Piggott wrote:
>>>
>>> I have no clue how many users care and read our ReleaseNotes, but
>>> important is that they have opportunity to do that and they have
>>> always time to adopt to changes. This is how I promised that this 
>>> project will be maintained. 
>>
>> Your response here puzzled me, because I could not remember you ever
>> making a pre-announcement of this nature before.
> 
> 2.14  The losetup(8) '-s' option (introduced by util-linux-ng-2.13) is deprecated
> 2.21  The udev compatible output (-o udev) from blkid(8) is deprecated.
> 2.25  The "swapon --summary" output format is deprecated ...
> 
> ... and many warnings about commands (mkfs, tailf, mount, last, ...) and
> features (cryptoloop).
> 
> The command line options are our API, we don't do such changes often.
> 
> I remember only one exception -- sfdisk, after rewrite some obscure
> DOS-era options have been removed.

We're not talking about deprecating anything, which is why I said "of
this nature". We're not changing any API or removing any options. We're
talking about changing the default output format. As was done to hwclock
without any advanced warning and, so far, without any complaints. I
could not find any past releases giving advanced warnings for changing a
default configuration.

I really expected someone to complain that we broke their script with
the hwclock change. I think it far more likely that hwclock's output be
used programmatically then cal's. If I wanted calendar related data in a
script I'd be more inclined to use date(1); it offers a lot more control
over its output. Isn't the concern for an advance warning that the
change would break the command's use programmatically? Cal's output isn't
machine friendly, I don't think. Isn't cal's intended audience human?

Anyway, it certainly doesn't hurt anything if you want to do this the
slow painful way. The end result is the same, although a bit more work.
I'm mostly trying to understand the rational, so that I know what to do
in future instances.

BTW, I also dropped 'PATCH 09/11 cal: remove the non-functional options'
from the 171229 branch.


> 
>     Karel
> 

Re: [v3 PATCH 00/11] Pull Request - changelog

[Karel Zak]

On Thu, Jan 11, 2018 at 08:35:51AM -0500, J William Piggott wrote:
> 
> 
> On 01/11/2018 04:01 AM, Karel Zak wrote:
> > On Wed, Jan 10, 2018 at 09:00:23PM -0500, J William Piggott wrote:
> >>
> >>
> >> On 01/08/2018 05:21 AM, Karel Zak wrote:
> >>> On Tue, Jan 02, 2018 at 09:53:18AM -0500, J William Piggott wrote:
> >>>
> >>> I have no clue how many users care and read our ReleaseNotes, but
> >>> important is that they have opportunity to do that and they have
> >>> always time to adopt to changes. This is how I promised that this 
> >>> project will be maintained. 
> >>
> >> Your response here puzzled me, because I could not remember you ever
> >> making a pre-announcement of this nature before.
> > 
> > 2.14  The losetup(8) '-s' option (introduced by util-linux-ng-2.13) is deprecated
> > 2.21  The udev compatible output (-o udev) from blkid(8) is deprecated.
> > 2.25  The "swapon --summary" output format is deprecated ...
> > 
> > ... and many warnings about commands (mkfs, tailf, mount, last, ...) and
> > features (cryptoloop).
> > 
> > The command line options are our API, we don't do such changes often.
> > 
> > I remember only one exception -- sfdisk, after rewrite some obscure
> > DOS-era options have been removed.
> 
> We're not talking about deprecating anything, which is why I said "of
> this nature". We're not changing any API or removing any options. 

Well, my mistake. I have thought about "rename --julian to --ordinal"
and errx(EXIT_FAILURE, ("use --ordinal, --julian has been deprecated."));

This change is too aggressive without ReleaseNotes warning.

> We're talking about changing the default output format. As was done
> to hwclock without any advanced warning and, so far, without any
> complaints. I could not find any past releases giving advanced
> warnings for changing a default configuration.

Hmm... the calculation change for the old dates (<1752) is probably 
not so big problem, although I can imagine that someone somewhere
depends on the current behavior. I'll think about it.

> Cal's output isn't machine friendly, I don't think. Isn't cal's
> intended audience human?

We should not use such presumptions. (And I remember emails and RHEL
reports from people who use cal(1) for research to see old dates, or
in scripts for some complex outputs, etc.) 

    Karel

-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com

Re: [v3 PATCH 00/11] Pull Request - changelog

[J William Piggott]

On 01/12/2018 05:57 AM, Karel Zak wrote:
> On Thu, Jan 11, 2018 at 08:35:51AM -0500, J William Piggott wrote:
>>
>>
>> On 01/11/2018 04:01 AM, Karel Zak wrote:
>>> On Wed, Jan 10, 2018 at 09:00:23PM -0500, J William Piggott wrote:
>>>>
>>>>
>>>> On 01/08/2018 05:21 AM, Karel Zak wrote:
>>>>> On Tue, Jan 02, 2018 at 09:53:18AM -0500, J William Piggott wrote:
>>>>>
>>>>> I have no clue how many users care and read our ReleaseNotes, but
>>>>> important is that they have opportunity to do that and they have
>>>>> always time to adopt to changes. This is how I promised that this 
>>>>> project will be maintained. 
>>>>
>>>> Your response here puzzled me, because I could not remember you ever
>>>> making a pre-announcement of this nature before.
>>>
>>> 2.14  The losetup(8) '-s' option (introduced by util-linux-ng-2.13) is deprecated
>>> 2.21  The udev compatible output (-o udev) from blkid(8) is deprecated.
>>> 2.25  The "swapon --summary" output format is deprecated ...
>>>
>>> ... and many warnings about commands (mkfs, tailf, mount, last, ...) and
>>> features (cryptoloop).
>>>
>>> The command line options are our API, we don't do such changes often.
>>>
>>> I remember only one exception -- sfdisk, after rewrite some obscure
>>> DOS-era options have been removed.
>>
>> We're not talking about deprecating anything, which is why I said "of
>> this nature". We're not changing any API or removing any options. 
> 
> Well, my mistake. I have thought about "rename --julian to --ordinal"
> and errx(EXIT_FAILURE, ("use --ordinal, --julian has been deprecated."));
> 
> This change is too aggressive without ReleaseNotes warning.
> 
 
I agree, it is aggressive.

Having considered your comments, I realize that my submissions are
likely the wrong solutions. The reality is, the practice of calling
'ordinal Gregorian calendars' 'Julian calendars' is deeply entrenched;
it's even in the POSIX standard. 

So, if we leave the --julian option as it is, what is the solution for
the name collision. Use some made-up name for a Julian calendar system
like --caesar. Sometimes Roman is used as an umbrella term for Roman and
Julian calendars combined. I don't think that's a good choice though,
because someone may get ambitious and implement output earlier than year
1; then it would be necessary to distinguish between Roman and Julian
calendars. Besides, to muddy the waters further by starting yet another
practice of using an incorrect name involving Julian just seems wrong.

I think the new option needs to be called Julian; so the only solution
left is to use a different name space. I propose the following:

* leave the current --julian option as is

* add one new option for setting the reform year:
   --reform-year=<gregorian|iso|julian|1752>

I think this approach would also be better if the other 20 Gregorian
reform adoption dates are ever added. 24 arguments would be cleaner then
having an equal number of separate options.

Then to address whether to set the proleptic Gregorian calendar system
as the default: I think just stay with your original plan, only forget
the last bullet point with regard to implementing the code; I tried
including preparations for the switch in the files, but it's too messy. So:

* leave the current default using 1752 reform

* create the proleptic Gregorian option

* let Karel decide if/when/how/politics of changing the default
  Maybe comments from closing the RedHat bug will help with that choice.

I mentioned before that I have more bug fixes queued, but didn't want to
make this patch set to large. Well, some of them influence handling of
the multiple calendar systems so I may add them to the next version of
this patch set.

Thoughts?

Re: [v3 PATCH 00/11] Pull Request - changelog

[Karel Zak]

On Sun, Jan 14, 2018 at 09:02:26PM -0500, J William Piggott wrote:
> On 01/12/2018 05:57 AM, Karel Zak wrote:

> > Well, my mistake. I have thought about "rename --julian to --ordinal"
> > and errx(EXIT_FAILURE, ("use --ordinal, --julian has been deprecated."));
> > 
> > This change is too aggressive without ReleaseNotes warning.
> > 
>  
> I agree, it is aggressive.
> 
> Having considered your comments, I realize that my submissions are
> likely the wrong solutions. The reality is, the practice of calling
> 'ordinal Gregorian calendars' 'Julian calendars' is deeply entrenched;
> it's even in the POSIX standard. 
> 
> So, if we leave the --julian option as it is, what is the solution for
> the name collision. Use some made-up name for a Julian calendar system
> like --caesar. Sometimes Roman is used as an umbrella term for Roman and
> Julian calendars combined. I don't think that's a good choice though,
> because someone may get ambitious and implement output earlier than year
> 1; then it would be necessary to distinguish between Roman and Julian
> calendars. Besides, to muddy the waters further by starting yet another
> practice of using an incorrect name involving Julian just seems wrong.
> 
> I think the new option needs to be called Julian; so the only solution
> left is to use a different name space. I propose the following:
> 
> * leave the current --julian option as is

Unfortunately, this is necessary.

> * add one new option for setting the reform year:
>    --reform-year=<gregorian|iso|julian|1752>

Yes, I think about something like this. It seems like a way how to
keep it extendable.

  * leave the current --julian option as is

  * --reform=<gregorian,1752,greek,...>

  * add --iso (as alias to --reform=gregorian)

> I think this approach would also be better if the other 20 Gregorian
> reform adoption dates are ever added. 24 arguments would be cleaner then
> having an equal number of separate options.

Yes.

> Then to address whether to set the proleptic Gregorian calendar system
> as the default: I think just stay with your original plan, only forget
> the last bullet point with regard to implementing the code; I tried
> including preparations for the switch in the files, but it's too messy. So:
> 
> * leave the current default using 1752 reform
> 
> * create the proleptic Gregorian option
> 
> * let Karel decide if/when/how/politics of changing the default
>   Maybe comments from closing the RedHat bug will help with that choice.
> 
> I mentioned before that I have more bug fixes queued, but didn't want to
> make this patch set to large. Well, some of them influence handling of
> the multiple calendar systems so I may add them to the next version of
> this patch set.

I hope I'll work on cal(1) this week. If you see any bug in the
current code, then fix it again the current master branch. I'll rebase
and merge it to the new code later... or wait ;-)

    Karel

-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com

Re: [v3 PATCH 00/11] Pull Request - changelog

[J William Piggott]

On 01/15/2018 08:36 AM, Karel Zak wrote:
> On Sun, Jan 14, 2018 at 09:02:26PM -0500, J William Piggott wrote:
>> On 01/12/2018 05:57 AM, Karel Zak wrote:
> 
>>> Well, my mistake. I have thought about "rename --julian to --ordinal"
>>> and errx(EXIT_FAILURE, ("use --ordinal, --julian has been deprecated."));
>>>
>>> This change is too aggressive without ReleaseNotes warning.
>>>
>>  
>> I agree, it is aggressive.
>>
>> Having considered your comments, I realize that my submissions are
>> likely the wrong solutions. The reality is, the practice of calling
>> 'ordinal Gregorian calendars' 'Julian calendars' is deeply entrenched;
>> it's even in the POSIX standard. 
>>
>> So, if we leave the --julian option as it is, what is the solution for
>> the name collision. Use some made-up name for a Julian calendar system
>> like --caesar. Sometimes Roman is used as an umbrella term for Roman and
>> Julian calendars combined. I don't think that's a good choice though,
>> because someone may get ambitious and implement output earlier than year
>> 1; then it would be necessary to distinguish between Roman and Julian
>> calendars. Besides, to muddy the waters further by starting yet another
>> practice of using an incorrect name involving Julian just seems wrong.
>>
>> I think the new option needs to be called Julian; so the only solution
>> left is to use a different name space. I propose the following:
>>
>> * leave the current --julian option as is
> 
> Unfortunately, this is necessary.
> 
>> * add one new option for setting the reform year:
>>    --reform-year=<gregorian|iso|julian|1752>
> 
> Yes, I think about something like this. It seems like a way how to
> keep it extendable.
> 
>   * leave the current --julian option as is
> 
>   * --reform=<gregorian,1752,greek,...>
> 
>   * add --iso (as alias to --reform=gregorian)
> 
>> I think this approach would also be better if the other 20 Gregorian
>> reform adoption dates are ever added. 24 arguments would be cleaner then
>> having an equal number of separate options.
> 
> Yes.
> 
>> Then to address whether to set the proleptic Gregorian calendar system
>> as the default: I think just stay with your original plan, only forget
>> the last bullet point with regard to implementing the code; I tried
>> including preparations for the switch in the files, but it's too messy. So:
>>
>> * leave the current default using 1752 reform
>>
>> * create the proleptic Gregorian option
>>
>> * let Karel decide if/when/how/politics of changing the default
>>   Maybe comments from closing the RedHat bug will help with that choice.
>>
>> I mentioned before that I have more bug fixes queued, but didn't want to
>> make this patch set to large. Well, some of them influence handling of
>> the multiple calendar systems so I may add them to the next version of
>> this patch set.
> 
> I hope I'll work on cal(1) this week. If you see any bug in the
> current code, then fix it again the current master branch. I'll rebase
> and merge it to the new code later... or wait ;-)

That's not cool Karel. You requested volunteers to do this for you. I've been
working on it for nearly a month, and now you want to pull it out from under me.

I'm submitting 2 patches that implement exactly what you've asked for; all by
the book; nothing removed, no short options, etc. Plus one patch to update the
man page. If there is something wrong with the submission I'd like some
constructive feedback so that I can fix it.

After that I'll submit individually the other bug fixes that I've found.

> 
>     Karel
> 

[v5 PATCH 1/3] cal: move REFORMATION_YEAR to control struct

[J William Piggott]

Signed-off-by: J William Piggott <elseifthen@gmx.com>
---
 misc-utils/cal.c | 86 ++++++++++++++++++++++++++++++++------------------------
 1 file changed, 49 insertions(+), 37 deletions(-)

diff --git a/misc-utils/cal.c b/misc-utils/cal.c
index 39f2bdcba..ea582964c 100644
--- a/misc-utils/cal.c
+++ b/misc-utils/cal.c
@@ -160,7 +160,6 @@ enum {
 	DECEMBER
 };
 
-#define REFORMATION_YEAR	1752		/* Signed-off-by: Lord Chesterfield */
 #define REFORMATION_MONTH	SEPTEMBER
 #define	NUMBER_MISSING_DAYS	11		/* 11 day correction */
 #define YDAY_AFTER_MISSING	258             /* 14th in Sep 1752 */
@@ -206,6 +205,7 @@ struct cal_control {
 	const char *full_month[MONTHS_IN_YEAR];	/* month names */
 	const char *abbr_month[MONTHS_IN_YEAR];	/* abbreviated month names */
 
+	int reform_year;		/* Gregorian reform year */
 	int colormode;			/* day and week number highlight */
 	int num_months;			/* number of requested months */
 	int span_months;		/* span the date */
@@ -230,7 +230,7 @@ struct cal_month {
 };
 
 /* function prototypes */
-static int leap_year(int32_t year);
+static int leap_year(const struct cal_control *ctl, int32_t year);
 static int monthname_to_number(struct cal_control *ctl, const char *name);
 static void headers_init(struct cal_control *ctl);
 static void cal_fill_month(struct cal_month *month, const struct cal_control *ctl);
@@ -238,8 +238,10 @@ static void cal_output_header(struct cal_month *month, const struct cal_control
 static void cal_output_months(struct cal_month *month, const struct cal_control *ctl);
 static void monthly(const struct cal_control *ctl);
 static void yearly(const struct cal_control *ctl);
-static int day_in_year(int day, int month, int32_t year);
-static int day_in_week(int day, int month, int32_t year);
+static int day_in_year(const struct cal_control *ctl, int day,
+		       int month, int32_t year);
+static int day_in_week(const struct cal_control *ctl, int day,
+		       int month, int32_t year);
 static int week_number(int day, int month, int32_t year, const struct cal_control *ctl);
 static int week_to_day(const struct cal_control *ctl);
 static int center_str(const char *src, char *dest, size_t dest_size, size_t width);
@@ -252,7 +254,9 @@ int main(int argc, char **argv)
 	char *term;
 	time_t now;
 	int ch = 0, yflag = 0, Yflag = 0;
+
 	static struct cal_control ctl = {
+		.reform_year = 1752,
 		.weekstart = SUNDAY,
 		.num_months = 1,		/* default is "cal -1" */
 		.span_months = 0,
@@ -335,7 +339,8 @@ int main(int argc, char **argv)
 		val.string = nl_langinfo(_NL_TIME_WEEK_1STDAY);
 
 		wfd = val.word;
-		wfd = day_in_week(wfd % 100, (wfd / 100) % 100, wfd / (100 * 100));
+		wfd = day_in_week(&ctl, wfd % 100, (wfd / 100) % 100,
+				  wfd / (100 * 100));
 		ctl.weekstart = (wfd + *nl_langinfo(_NL_TIME_FIRST_WEEKDAY) - 1) % DAYS_IN_WEEK;
 	}
 #endif
@@ -451,10 +456,12 @@ int main(int argc, char **argv)
 		if (ctl.req.year == INT32_MAX)
 			errx(EXIT_FAILURE, _("illegal year value"));
 		if (ctl.req.day) {
-			int dm = days_in_month[leap_year(ctl.req.year)][ctl.req.month];
+			int dm = days_in_month[leap_year(&ctl, ctl.req.year)]
+					      [ctl.req.month];
 			if (ctl.req.day > dm)
 				errx(EXIT_FAILURE, _("illegal day value: use 1-%d"), dm);
-			ctl.req.day = day_in_year(ctl.req.day, ctl.req.month, ctl.req.year);
+			ctl.req.day = day_in_year(&ctl, ctl.req.day,
+						  ctl.req.month, ctl.req.year);
 		} else if ((int32_t) (local_time->tm_year + 1900) == ctl.req.year) {
 			ctl.req.day = local_time->tm_yday + 1;
 		}
@@ -476,7 +483,7 @@ int main(int argc, char **argv)
 
 	if (0 < ctl.req.week) {
 		int yday = week_to_day(&ctl);
-		int leap = leap_year(ctl.req.year);
+		int leap = leap_year(&ctl, ctl.req.year);
 		int m = 1;
 
 		if (yday < 1)
@@ -532,9 +539,9 @@ int main(int argc, char **argv)
 }
 
 /* leap year -- account for gregorian reformation in 1752 */
-static int leap_year(int32_t year)
+static int leap_year(const struct cal_control *ctl, int32_t year)
 {
-	if (year <= REFORMATION_YEAR)
+	if (year <= ctl->reform_year)
 		return !(year % 4);
 	else
 		return ( !(year % 4) && (year % 100) ) || !(year % 400);
@@ -618,15 +625,15 @@ static void headers_init(struct cal_control *ctl)
 
 static void cal_fill_month(struct cal_month *month, const struct cal_control *ctl)
 {
-	int first_week_day = day_in_week(1, month->month, month->year);
+	int first_week_day = day_in_week(ctl, 1, month->month, month->year);
 	int month_days;
 	int i, j, weeklines = 0;
 
 	if (ctl->julian)
-		j = day_in_year(1, month->month, month->year);
+		j = day_in_year(ctl, 1, month->month, month->year);
 	else
 		j = 1;
-	month_days = j + days_in_month[leap_year(month->year)][month->month];
+	month_days = j + days_in_month[leap_year(ctl, month->year)][month->month];
 
 	/* True when Sunday is not first day in the output week. */
 	if (ctl->weekstart) {
@@ -644,7 +651,9 @@ static void cal_fill_month(struct cal_month *month, const struct cal_control *ct
 			continue;
 		}
 		if (j < month_days) {
-			if (month->year == REFORMATION_YEAR && month->month == REFORMATION_MONTH && (j == 3 || j == 247))
+			if (month->year == ctl->reform_year &&
+			    month->month == REFORMATION_MONTH &&
+			    (j == 3 || j == 247))
 				j += NUMBER_MISSING_DAYS;
 			month->days[i] = j;
 			j++;
@@ -726,9 +735,9 @@ static void cal_output_months(struct cal_month *month, const struct cal_control
 				if (ctl->julian)
 					reqday = ctl->req.day;
 				else
-					reqday =
-					    ctl->req.day + 1 - day_in_year(1, i->month,
-									   i->year);
+					reqday = ctl->req.day + 1 -
+						 day_in_year(ctl, 1, i->month,
+							     i->year);
 			}
 
 			if (ctl->weektype) {
@@ -847,11 +856,12 @@ static void yearly(const struct cal_control *ctl)
  * day_in_year --
  *	return the 1 based day number within the year
  */
-static int day_in_year(int day, int month, int32_t year)
+static int day_in_year(const struct cal_control *ctl,
+		       int day, int month, int32_t year)
 {
 	int i, leap;
 
-	leap = leap_year(year);
+	leap = leap_year(ctl, year);
 	for (i = 1; i < month; i++)
 		day += days_in_month[leap][i];
 	return day;
@@ -864,7 +874,8 @@ static int day_in_year(int day, int month, int32_t year)
  *	3 Sep. 1752 through 13 Sep. 1752, and returns invalid weekday
  *	during the period of 11 days.
  */
-static int day_in_week(int day, int month, int32_t year)
+static int day_in_week(const struct cal_control *ctl, int day,
+		       int month, int32_t year)
 {
 	/*
 	* The magic constants in the reform[] array are, in a simplified
@@ -886,20 +897,21 @@ static int day_in_week(int day, int month, int32_t year)
 	static const int reform[] = { 0, 3, 2, 5, 0, 3, 5, 1, 4, 6, 2, 4 };
 	static const int old[]    = { 5, 1, 0, 3, 5, 1, 3, 6, 2, 4, 0, 2 };
 
-	if (year != REFORMATION_YEAR + 1)
+	if (year != ctl->reform_year + 1)
 		year -= month < MARCH;
 	else
 		year -= (month < MARCH) + 14;
-	if (REFORMATION_YEAR < year
-	    || (year == REFORMATION_YEAR && REFORMATION_MONTH < month)
-	    || (year == REFORMATION_YEAR && month == REFORMATION_MONTH && 13 < day)) {
+	if (ctl->reform_year < year
+	    || (year == ctl->reform_year && REFORMATION_MONTH < month)
+	    || (year == ctl->reform_year
+		&& month == REFORMATION_MONTH && 13 < day)) {
 		int64_t long_year = year;
-		return (long_year + (year / 4) - (year / 100) + (year / 400) + reform[month - 1] +
-			day) % DAYS_IN_WEEK;
+		return (long_year + (year / 4) - (year / 100) + (year / 400) +
+			reform[month - 1] + day) % DAYS_IN_WEEK;
 	}
-	if (year < REFORMATION_YEAR
-	    || (year == REFORMATION_YEAR && month < REFORMATION_MONTH)
-	    || (year == REFORMATION_YEAR && month == REFORMATION_MONTH && day < 3))
+	if (year < ctl->reform_year
+	    || (year == ctl->reform_year && month < REFORMATION_MONTH)
+	    || (year == ctl->reform_year && month == REFORMATION_MONTH && day < 3))
 		return (year + year / 4 + old[month - 1] + day) % DAYS_IN_WEEK;
 	return NONEDAY;
 }
@@ -914,7 +926,7 @@ static int day_in_week(int day, int month, int32_t year)
 static int week_number(int day, int month, int32_t year, const struct cal_control *ctl)
 {
 	int fday = 0, yday;
-	const int wday = day_in_week(1, JANUARY, year);
+	const int wday = day_in_week(ctl, 1, JANUARY, year);
 
 	if (ctl->weektype & WEEK_NUM_ISO)
 		fday = wday + (wday >= FRIDAY ? -2 : 5);
@@ -930,8 +942,8 @@ static int week_number(int day, int month, int32_t year, const struct cal_contro
 	if (day > DAYS_IN_MONTH)
 		month = JANUARY;
 
-	yday = day_in_year(day,month,year);
-	if (year == REFORMATION_YEAR && yday >= YDAY_AFTER_MISSING)
+	yday = day_in_year(ctl, day, month, year);
+	if (year == ctl->reform_year && yday >= YDAY_AFTER_MISSING)
 		fday -= NUMBER_MISSING_DAYS;
 
 	/* Last year is last year */
@@ -942,10 +954,10 @@ static int week_number(int day, int month, int32_t year, const struct cal_contro
 	 * days than 365 making this check invalid, but reformation year ended
 	 * on Sunday and in week 51, so it's ok here. */
 	if (ctl->weektype == WEEK_NUM_ISO && yday >= 363
-	    && day_in_week(day, month, year) >= MONDAY
-	    && day_in_week(day, month, year) <= WEDNESDAY
-	    && day_in_week(31, DECEMBER, year) >= MONDAY
-	    && day_in_week(31, DECEMBER, year) <= WEDNESDAY)
+	    && day_in_week(ctl, day, month, year) >= MONDAY
+	    && day_in_week(ctl, day, month, year) <= WEDNESDAY
+	    && day_in_week(ctl, 31, DECEMBER, year) >= MONDAY
+	    && day_in_week(ctl, 31, DECEMBER, year) <= WEDNESDAY)
 		return week_number(1, JANUARY, year + 1, ctl);
 
 	return (yday + fday) / DAYS_IN_WEEK;
@@ -962,7 +974,7 @@ static int week_to_day(const struct cal_control *ctl)
 {
 	int yday, wday;
 
-	wday = day_in_week(1, JANUARY, ctl->req.year);
+	wday = day_in_week(ctl, 1, JANUARY, ctl->req.year);
 	yday = ctl->req.week * DAYS_IN_WEEK - wday;
 
 	if (ctl->weektype & WEEK_NUM_ISO)

[v5 PATCH 2/3] cal: add option to set Gregorian reform date

[J William Piggott]

Create the new option: --reform <1752|gregorian|iso|julian>

This adds the capability to display either the proleptic Gregorian or
the Julian calendar systems exclusively.

Also create the option --iso as alias of --reform=gregorian.

Signed-off-by: J William Piggott <elseifthen@gmx.com>
---
 misc-utils/cal.c | 53 +++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 49 insertions(+), 4 deletions(-)

diff --git a/misc-utils/cal.c b/misc-utils/cal.c
index ea582964c..543fbc6e1 100644
--- a/misc-utils/cal.c
+++ b/misc-utils/cal.c
@@ -133,6 +133,14 @@ static const char *my_tgetstr(char *ss
 
 #include "widechar.h"
 
+enum {
+	GREGORIAN		= INT32_MIN,
+	ISO			= INT32_MIN,
+	GB1752			= 1752,
+	DEFAULT_REFORM_YEAR	= 1752,
+	JULIAN			= INT32_MAX
+};
+
 enum {
 	SUNDAY = 0,
 	MONDAY,
@@ -246,6 +254,7 @@ static int week_number(int day, int month, int32_t year, const struct cal_contro
 static int week_to_day(const struct cal_control *ctl);
 static int center_str(const char *src, char *dest, size_t dest_size, size_t width);
 static void center(const char *str, size_t len, int separate);
+static int parse_reform_year(const char *reform_year);
 static void __attribute__((__noreturn__)) usage(void);
 
 int main(int argc, char **argv)
@@ -256,7 +265,7 @@ int main(int argc, char **argv)
 	int ch = 0, yflag = 0, Yflag = 0;
 
 	static struct cal_control ctl = {
-		.reform_year = 1752,
+		.reform_year = DEFAULT_REFORM_YEAR,
 		.weekstart = SUNDAY,
 		.num_months = 1,		/* default is "cal -1" */
 		.span_months = 0,
@@ -269,7 +278,9 @@ int main(int argc, char **argv)
 	};
 
 	enum {
-		OPT_COLOR = CHAR_MAX + 1
+		OPT_COLOR = CHAR_MAX + 1,
+		OPT_ISO,
+		OPT_REFORM
 	};
 
 	static const struct option longopts[] = {
@@ -283,6 +294,8 @@ int main(int argc, char **argv)
 		{"year", no_argument, NULL, 'y'},
 		{"week", optional_argument, NULL, 'w'},
 		{"color", optional_argument, NULL, OPT_COLOR},
+		{"reform", required_argument, NULL, OPT_REFORM},
+		{"iso", no_argument, NULL, OPT_ISO},
 		{"version", no_argument, NULL, 'V'},
 		{"twelve", no_argument, NULL, 'Y'},
 		{"help", no_argument, NULL, 'h'},
@@ -395,6 +408,12 @@ int main(int argc, char **argv)
 				ctl.colormode = colormode_or_err(optarg,
 						_("unsupported color mode"));
 			break;
+		case OPT_REFORM:
+			ctl.reform_year = parse_reform_year(optarg);
+			break;
+		case OPT_ISO:
+			ctl.reform_year = ISO;
+			break;
 		case 'V':
 			printf(UTIL_LINUX_VERSION);
 			return EXIT_SUCCESS;
@@ -453,7 +472,7 @@ int main(int argc, char **argv)
 		ctl.req.year = strtos32_or_err(*argv++, _("illegal year value"));
 		if (ctl.req.year < SMALLEST_YEAR)
 			errx(EXIT_FAILURE, _("illegal year value: use positive integer"));
-		if (ctl.req.year == INT32_MAX)
+		if (ctl.req.year == JULIAN)
 			errx(EXIT_FAILURE, _("illegal year value"));
 		if (ctl.req.day) {
 			int dm = days_in_month[leap_year(&ctl, ctl.req.year)]
@@ -1012,6 +1031,30 @@ static void center(const char *str, size_t len, int separate)
 	}
 }
 
+static int parse_reform_year(const char *reform_year)
+{
+	size_t i;
+
+	struct reform {
+		char *name;
+		int val;
+	};
+
+	struct reform years[] = {
+	{"gregorian",	GREGORIAN},
+	{"iso",		ISO},
+	{"1752",	GB1752},
+	{"julian",	JULIAN},
+	};
+
+	for (i = 0; i < ARRAY_SIZE(years); i++) {
+		if (strcasecmp(reform_year, years[i].name) == 0) {
+			return years[i].val;
+		}
+	}
+	errx(EXIT_FAILURE, "invalid --reform value: '%s'", reform_year);
+}
+
 static void __attribute__((__noreturn__)) usage(void)
 {
 	FILE *out = stdout;
@@ -1030,7 +1073,9 @@ static void __attribute__((__noreturn__)) usage(void)
 	fputs(_(" -S, --span            span the date when displaying multiple months\n"), out);
 	fputs(_(" -s, --sunday          Sunday as first day of week\n"), out);
 	fputs(_(" -m, --monday          Monday as first day of week\n"), out);
-	fputs(_(" -j, --julian          output Julian dates\n"), out);
+	fputs(_(" -j, --julian          use day-of-year for all calendars\n"), out);
+	fputs(_("     --reform <val>    Gregorian reform date (1752|gregorian|iso|julian)\n"), out);
+	fputs(_("     --iso             alias for --reform=iso\n"), out);
 	fputs(_(" -y, --year            show the whole year\n"), out);
 	fputs(_(" -Y, --twelve          show the next twelve months\n"), out);
 	fputs(_(" -w, --week[=<num>]    show US or ISO-8601 week numbers\n"), out);

[v5 PATCH 3/3] cal: update man page

[J William Piggott]

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>
---
 misc-utils/cal.1 | 83 ++++++++++++++++++++++++++++++++++++++++++++++++++------
 1 file 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.

Re: [v3 PATCH 00/11] Pull Request - changelog

[Karel Zak]

On Tue, Jan 16, 2018 at 04:35:47PM -0500, J William Piggott wrote:
> > I hope I'll work on cal(1) this week. If you see any bug in the
> > current code, then fix it again the current master branch. I'll rebase
> > and merge it to the new code later... or wait ;-)
> 
> That's not cool Karel. You requested volunteers to do this for you. I've been
> working on it for nearly a month, and now you want to pull it out from under me.

Ah, I don't want to say I'll ignore your patches or so. This is
misunderstanding... anyway merged!

> I'm submitting 2 patches that implement exactly what you've asked for; all by
> the book; nothing removed, no short options, etc. Plus one patch to update the
> man page. If there is something wrong with the submission I'd like some
> constructive feedback so that I can fix it.

Yes, sounds good. Thanks! (and thanks for patience with stubborn
maintainer;-)


I'm not sure about the way how the current cal(1) code handles the
reform. It's all based on "year", but it could be more complex if we
want to make it extendable and support another reforms too. This is
what I'd like to change.

The ideal would be to describe the reform by any struct (as good
programming is about data structures rather than about code:-).


struct cal_reform {
    int year;
    int month;
    int day;
    int missing_days;
};

static const struct reforms[] = {
    [REFORM_GB_1752] = { 
        .year = 1752,
        .month = SEPTEMBER,
        .day = 2,
        .missing_days = 11
    },
    [REFORM_GREEK_1923] = {
        .year = 1923,
        .month = FEBRUARY,
        .day = 16,
        .missing_days = 12
    }
    ...
};

/*
 * Names and aliases used in --help output and for getopt()
 */
struct cal_reform_names {
    const char *name;
    int id;
    const char *desc;
};

static const struct reform_names[] = {
    { "1752", REFORM_GB_1752, _N("British Empire reform (September 1752)")_ },
    ...
};


main():
    ctl.reform = &reforms[REFORM_GB_1752];
...


day_in_week():
    struct cal_reform *re = ctl->reform;

	if (re->year < year
	    || (year == re->year && re->month < month)
	    || (year == re->year
		&& month == re->month && re->day + re->missing_days < day)) {

        ...
	}

Comments? 

IMHO it's better and more readable than the current hardcoded stuff.


The remaining thing is magic constants for day-in-week calculations.
It's fast/elegant for Gregorian (ISO) calendar, but I'm not sure about
old calendars. 

Maybe the original calculation before 91ac9ef5db449b38e679e85483f2dc6d9a56e1ce
has been more readable (based on leap_years_since_year_1() and easy to adopt 
to another calendars. Ideas?

    Karel


-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com

Re: [v3 PATCH 00/11] Pull Request - changelog

[J William Piggott]

On 01/17/2018 07:08 AM, Karel Zak wrote:
> On Tue, Jan 16, 2018 at 04:35:47PM -0500, J William Piggott wrote:
>>> I hope I'll work on cal(1) this week. If you see any bug in the
>>> current code, then fix it again the current master branch. I'll rebase
>>> and merge it to the new code later... or wait ;-)
>>
>> That's not cool Karel. You requested volunteers to do this for you. I've been
>> working on it for nearly a month, and now you want to pull it out from under me.
> 
> Ah, I don't want to say I'll ignore your patches or so. This is
> misunderstanding... anyway merged!
> 
>> I'm submitting 2 patches that implement exactly what you've asked for; all by
>> the book; nothing removed, no short options, etc. Plus one patch to update the
>> man page. If there is something wrong with the submission I'd like some
>> constructive feedback so that I can fix it.
> 
> Yes, sounds good. Thanks! (and thanks for patience with stubborn
> maintainer;-)

Well, it took me 5 versions before coming around. So thank you for your
patience also. Hopefully, in the end, these discussions on various
design options yields the best results.

> I'm not sure about the way how the current cal(1) code handles the
> reform. It's all based on "year", but it could be more complex if we
> want to make it extendable and support another reforms too.

I think this is an important question to answer before making design
choices. Do you want to add more reform dates?

Time keeping is very geopolitical. For example, the tz database
(zoneinfo) is plagued by complaints of political nature like: "you have
county x, y, and z; why do you exclude my country? Why are you treating
us like second class country?"

This has become so frustrating that some contributors are advocating to
strip the db of all geographic connections and label the various
timezones with random hashes.

So do you intend to:

 a) selectively add a few more reform dates and deal with the potentially
    political strife it may bring to the project?

 b) add all reform dates?
     If yes, how would complex regions like Latvia, Netherlands, Sweden,
     and Russia be implemented? (very difficult I think)

 c) do not add any more reform dates?
     Then the reform structs would not be useful.

Currently I think there is a good answer if anyone requested to add more
reform dates:

"The Chesterfield reform is a historical feature of cal(1) and part of
the POSIX standard, so it cannot be removed. We will not be adding any
new reform dates. Reform dates can be examined by having cal display the
date in both the Gregorian and Julian calendar systems."

This is one reason that I thought adding exclusive Julian calendar
output was a good feature; any reform date can be examined. It also
allows regions, other than the 'British Empire" to display their proper
dates. For example, Greece can now view dates prior to 1923-02-16 using
Julian calendars. Of course, this puts the onus of knowing the reform
date on the user.

8< ---

> 
> day_in_week():
>     struct cal_reform *re = ctl->reform;
> 
> 	if (re->year < year
> 	    || (year == re->year && re->month < month)
> 	    || (year == re->year
> 		&& month == re->month && re->day + re->missing_days < day)) {
> 
>         ...
> 	}

This will break for regions like Prussia where the reform crosses a
month boundary.

Also here, and some other places I think:
	month->month == REFORMATION_MONTH &&
	(j == 3 || j == 247))
		j += NUMBER_MISSING_DAYS;


This code I'm not sure about:
	if (year != ctl->reform_year + 1)
		year -= month < MARCH;
	else
		year -= (month < MARCH) + 14;

The first branch is easy; normally Jan and Feb day-of-week are based on
the previous year because of the potential jump on March 1st for leap
years.

The second branch is making a correction for the year following the reform
adoption, because in that case Jan 1 of the previous year would be a
Julian calendar date and won't work. What I'm not sure about is where the
constant '14' derives from. It may be the first day of the new Gregorian
calendar implementation 14 Sept 1752. If so, will simply substituting
other reform dates first_day work? This function is all about leap
years, this branch would impact that. 1752 happens to be a leap year for
both Gregorian and Julian systems. What will happen for regions like
Switzerland where the reform year is a leap year for Gregorian but not
for Julian?

I don't know to what extent, but my instinct is that cal's code is very
specific to 3 Sept 1752 and simply plugging other reform dates into it
will be brittle.

So sure, more reform dates could be added; I think it may be complex to
implement though. I've only given some examples, there are more places
in the code tied to the current reform date.

> IMHO it's better and more readable than the current hardcoded stuff.

True, if the plan is to add more reform dates; otherwise the reform day
could be a preprocessor define like REFORMATION_MONTH,
NUMBER_MISSING_DAYS, and YDAY_AFTER_MISSING are.

> The remaining thing is magic constants for day-in-week calculations.
> It's fast/elegant for Gregorian (ISO) calendar, but I'm not sure about
> old calendars. 

So, the names for the reform[] and old[] arrays are not so good. They
should be gregorian and julian, or just greg and juli. They will work
for any date in there respective calendar systems. Since those are the
only two systems that cal uses, the constants should work as expected.

> Maybe the original calculation before 91ac9ef5db449b38e679e85483f2dc6d9a56e1ce
> has been more readable (based on leap_years_since_year_1() and easy to adopt 
> to another calendars. Ideas?

Not needed, IMO.

> 
>     Karel
> 
> 

Re: [v3 PATCH 00/11] Pull Request - changelog

[Karel Zak]

On Thu, Jan 18, 2018 at 11:32:14AM -0500, J William Piggott wrote:
> > I'm not sure about the way how the current cal(1) code handles the
> > reform. It's all based on "year", but it could be more complex if we
> > want to make it extendable and support another reforms too.
> 
> I think this is an important question to answer before making design
> choices. Do you want to add more reform dates?

It seems on many places Gregorian calendar have been adopted in
previous century so I guess it could be interesting to get appropriate
dates for actors, novelists, painters, researchers, etc... 

The feature seems unique and we already need to support it for GB.

> Time keeping is very geopolitical. For example, the tz database
> (zoneinfo) is plagued by complaints of political nature like: "you have
> county x, y, and z; why do you exclude my country? Why are you treating
> us like second class country?"

Oh, all history of this project is proof that we're able to be distro,
ethnic, language, etc. independent. I've spent many (Red Hat paid)
weeks to make things usable for almost everyone.  If anyone will blame me
for any political games I will very quickly redirect him to very dark
places... ;-)

>  b) add all reform dates?
>      If yes, how would complex regions like Latvia, Netherlands, Sweden,
>      and Russia be implemented? (very difficult I think)

Well, we can add what we have information about the reform. We don't
have to add "all" from the beginning. The another stuff could be added
later. It's open source, "send patch" is valid reaction :-)

    --reform <year>-<region> | <alias>

where <region> is name of the area in time the reform has been
implemented.

    --reform 1600-prussia
    --reform 1648-alsace

and we can add aliases

    --reform 1600-germany

btw, it's already controversial for GB too, it's "Great Britain and
colonies", I guess that some people can feel uncomfortable that
their region is "colonies" :-)

> "The Chesterfield reform is a historical feature of cal(1) and part of
> the POSIX standard, so it cannot be removed. We will not be adding any
> new reform dates. Reform dates can be examined by having cal display the
> date in both the Gregorian and Julian calendar systems."
> 
> This is one reason that I thought adding exclusive Julian calendar
> output was a good feature; any reform date can be examined. It also
> allows regions, other than the 'British Empire" to display their proper
> dates. For example, Greece can now view dates prior to 1923-02-16 using
> Julian calendars. Of course, this puts the onus of knowing the reform
> date on the user.

Yes, this is possible way. I think all the question is if we
want to invert man power to this feature. We can also end this
discussion with "it would be nice ... let's add to TODO" ;-)

> > 	if (re->year < year
> > 	    || (year == re->year && re->month < month)
> > 	    || (year == re->year
> > 		&& month == re->month && re->day + re->missing_days < day)) {
> > 
> >         ...
> > 	}
> 
> This will break for regions like Prussia where the reform crosses a
> month boundary.

Well, it was example, no attempt to implement it ;-)

> 	if (year != ctl->reform_year + 1)
> 		year -= month < MARCH;
> 	else
> 		year -= (month < MARCH) + 14;
> 
> The first branch is easy; normally Jan and Feb day-of-week are based on
> the previous year because of the potential jump on March 1st for leap
> years.
> 
> The second branch is making a correction for the year following the reform
> adoption, because in that case Jan 1 of the previous year would be a
> Julian calendar date and won't work. What I'm not sure about is where the
> constant '14' derives from. It may be the first day of the new Gregorian
> calendar implementation 14 Sept 1752. If so, will simply substituting
> other reform dates first_day work? This function is all about leap
> years, this branch would impact that. 1752 happens to be a leap year for
> both Gregorian and Julian systems. What will happen for regions like
> Switzerland where the reform year is a leap year for Gregorian but not
> for Julian?

Well, all the reform is just jump in calendar, from one day to
another, from one calculation method to another. The current code mix
it together, but is it really necessary? I guess you can just jump in
time and start use Gregorian calendar independently on the previous
Julian stuff (independently on leap year, etc.).

> I don't know to what extent, but my instinct is that cal's code is very
> specific to 3 Sept 1752 and simply plugging other reform dates into it
> will be brittle.

Yes, I agree the current code is very 1752-centric (and it's not too
elegant ;-)

> > The remaining thing is magic constants for day-in-week calculations.
> > It's fast/elegant for Gregorian (ISO) calendar, but I'm not sure about
> > old calendars. 
> 
> So, the names for the reform[] and old[] arrays are not so good. They
> should be gregorian and julian, or just greg and juli. They will work
> for any date in there respective calendar systems. Since those are the
> only two systems that cal uses, the constants should work as expected.

I read again https://en.wikipedia.org/wiki/Determination_of_the_day_of_the_week#T.C3.B8ndering.27s_algorithm
and it makes more sense for me now. So, this is no problem.

    Karel

-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com