* 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.
--
2.17.1
