tzdata/backport-Minor-editorial-improvements-for-newstrftime.3.patch

From 6e2e87703135d4923e9d65b4d75086341564401f Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@cs.ucla.edu>
Date: Sat, 8 Aug 2020 11:08:24 -0700
Subject: [PATCH 23/47] Minor editorial improvements for newstrftime.3
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* newstrftime.3: Improve this a bit to have it match POSIX better.
Resurrect the BSD manual’s phase-of-the-moon joke.
---
 newstrftime.3 | 103 +++++++++++++++++++++++++++++++++++++---------------------
 1 file changed, 66 insertions(+), 37 deletions(-)

diff --git a/newstrftime.3 b/newstrftime.3
index df38d1a..63842c7 100644
--- a/newstrftime.3
+++ b/newstrftime.3
@@ -50,12 +50,14 @@ strftime \- format date and time
 .B cc ... \-ltz
 .fi
 .SH DESCRIPTION
-.ie '\(en'' .ds en \-
-.el .ds en \(en
 .ie '\(lq'' .ds lq \&"\"
 .el .ds lq \(lq\"
 .ie '\(rq'' .ds rq \&"\"
 .el .ds rq \(rq\"
+.de c
+.ie \n(.g \f(CW\\$1\fP\\$2
+.el \\$1\\$2
+..
 .de q
 \\$3\*(lq\\$1\*(rq\\$2
 ..
@@ -63,7 +65,7 @@ The
 .B strftime
 function formats the information from
 .I timeptr
-into the buffer
+into the array pointed to by
 .I buf
 according to the string pointed to by
 .IR format .
@@ -72,24 +74,24 @@ The
 .I format
 string consists of zero or more conversion specifications and
 ordinary characters.
-All ordinary characters are copied directly into the buffer.
+All ordinary characters are copied directly into the array.
 A conversion specification consists of a percent sign
 .Ql %
 and one other character.
 .PP
 No more than
 .I maxsize
-characters are placed into the array.
-If the total number of resulting characters, including the terminating
-null character, is not more than
+bytes are placed into the array.
+If the total number of resulting bytes, including the terminating
+NUL character, is not more than
 .IR maxsize ,
 .B strftime
-returns the number of characters in the array, not counting the
-terminating null.
-Otherwise, zero is returned.
+returns the number of bytes placed into the array, not counting the
+terminating NUL.
+Otherwise, zero is returned and the array contents are unspecified.
 .PP
 Each conversion specification is replaced by the characters as
-follows which are then copied into the buffer.
+follows which are then copied into the array.
 .TP
 %A
 is replaced by the locale's full weekday name.
@@ -105,99 +107,122 @@ is replaced by the locale's abbreviated month name.
 .TP
 %C
 is replaced by the century (a year divided by 100 and truncated to an integer)
-as a decimal number (00\*(en99).
+as a decimal number [00,99].
 .TP
 %c
 is replaced by the locale's appropriate date and time representation.
 .TP
 %D
-is replaced by the date in the format %m/%d/%y.
+is equivalent to
+.c %m/%d/%y .
 .TP
 %d
-is replaced by the day of the month as a decimal number (01\*(en31).
+is replaced by the day of the month as a decimal number [01,31].
 .TP
 %e
-is replaced by the day of month as a decimal number (1\*(en31);
+is replaced by the day of month as a decimal number [1,31];
 single digits are preceded by a blank.
 .TP
 %F
-is replaced by the date in the format %Y\*-%m\*-%d.
+is equivalent to
+.c %Y-%m-%d
+(the ISO 8601 date format).
 .TP
 %G
 is replaced by the ISO 8601 year with century as a decimal number.
+See also the
+.c %V
+conversion specification.
 .TP
 %g
-is replaced by the ISO 8601 year without century as a decimal number (00\*(en99).
+is replaced by the ISO 8601 year without century as a decimal number [00,99].
+This is the year that includes the greater part of the week.
+(Monday as the first day of a week).
+See also the
+.c %V
+conversion specification.
 .TP
 %H
-is replaced by the hour (24-hour clock) as a decimal number (00\*(en23).
+is replaced by the hour (24-hour clock) as a decimal number [00,23].
 .TP
 %I
-is replaced by the hour (12-hour clock) as a decimal number (01\*(en12).
+is replaced by the hour (12-hour clock) as a decimal number [01,12].
 .TP
 %j
-is replaced by the day of the year as a decimal number (001\*(en366).
+is replaced by the day of the year as a decimal number [001,366].
 .TP
 %k
-is replaced by the hour (24-hour clock) as a decimal number (0\*(en23);
+is replaced by the hour (24-hour clock) as a decimal number [0,23];
 single digits are preceded by a blank.
 .TP
 %l
-is replaced by the hour (12-hour clock) as a decimal number (1\*(en12);
+is replaced by the hour (12-hour clock) as a decimal number [1,12];
 single digits are preceded by a blank.
 .TP
 %M
-is replaced by the minute as a decimal number (00\*(en59).
+is replaced by the minute as a decimal number [00,59].
 .TP
 %m
-is replaced by the month as a decimal number (01\*(en12).
+is replaced by the month as a decimal number [01,12].
 .TP
 %n
 is replaced by a newline.
 .TP
 %p
-is replaced by the locale's equivalent of either AM or PM.
+is replaced by the locale's equivalent of either
+.q AM
+or
+.q PM .
 .TP
 %R
-is replaced by the time in the format %H:%M.
+is replaced by the time in the format
+.c %H:%M .
 .TP
 %r
 is replaced by the locale's representation of 12-hour clock time
 using AM/PM notation.
 .TP
 %S
-is replaced by the second as a decimal number (00\*(en60).
+is replaced by the second as a decimal number [00,60].
+The range of
+seconds is [00,60] instead of [00,59] to allow for the periodic occurrence
+of leap seconds.
 .TP
 %s
-is replaced by the number of seconds since the Epoch (see newctime(3)).
+is replaced by the number of seconds since the Epoch (see
+.BR ctime (3)).
 .TP
 %T
-is replaced by the time in the format %H:%M:%S.
+is replaced by the time in the format
+.c %H:%M:%S .
 .TP
 %t
 is replaced by a tab.
 .TP
 %U
 is replaced by the week number of the year (Sunday as the first day of
-the week) as a decimal number (00\*(en53).
+the week) as a decimal number [00,53].
 .TP
 %u
 is replaced by the weekday (Monday as the first day of the week)
-as a decimal number (1\*(en7).
+as a decimal number [1,7].
 .TP
 %V
 is replaced by the week number of the year (Monday as the first day of
-the week) as a decimal number (01\*(en53).  If the week containing January
+the week) as a decimal number [01,53].  If the week containing January
 1 has four or more days in the new year, then it is week 1; otherwise
 it is week 53 of the previous year, and the next week is week 1.
+The year is given by the
+.c %G
+conversion specification.
 .TP
 %W
 is replaced by the week number of the year (Monday as the first day of
-the week) as a decimal number (00\*(en53).
+the week) as a decimal number [00,53].
 .TP
 %w
 is replaced by the weekday (Sunday as the first day of the week)
-as a decimal number (0\*(en6).
+as a decimal number [0,6].
 .TP
 %X
 is replaced by the locale's appropriate time representation.
@@ -209,7 +234,7 @@ is replaced by the locale's appropriate date representation.
 is replaced by the year with century as a decimal number.
 .TP
 %y
-is replaced by the year without century as a decimal number (00\*(en99).
+is replaced by the year without century as a decimal number [00,99].
 .TP
 %Z
 is replaced by the time zone abbreviation,
@@ -217,7 +242,7 @@ or by the empty string if this is not determinable.
 .TP
 %z
 is replaced by the offset from the Prime Meridian
-in the format +HHMM or \*-HHMM as appropriate,
+in the format +HHMM or \*-HHMM (ISO 8601) as appropriate,
 with positive values representing locations east of Greenwich,
 or by the empty string if this is not determinable.
 The numeric time zone abbreviation \*-0000 is used when the time is
@@ -231,7 +256,9 @@ time zone abbreviation begins with
 is replaced by a single %.
 .TP
 %+
-is replaced by the date and time in date(1) format.
+is replaced by the locale's date and time in
+.BR date (1)
+format.
 .SH SEE ALSO
 date(1),
 getenv(3),
@@ -239,3 +266,5 @@ newctime(3),
 newtzset(3),
 time(2),
 tzfile(5)
+.SH BUGS
+There is no conversion specification for the phase of the moon.
-- 
1.8.3.1