Re: git: 3c9f304b383b - main - Describe modern time zone handling.

Hey Greg,

I've noticed a couple of minor issues in the patch.

On 28/03/2022 05:59, Greg Lehey wrote:
> The branch main has been updated by grog:
>
> URL: https://cgit.FreeBSD.org/src/commit/?id=3c9f304b383bd378757ac33393b02f457947bc50
>
> commit 3c9f304b383bd378757ac33393b02f457947bc50
> Author:     Greg Lehey <grog@FreeBSD.org>
> AuthorDate: 2022-03-28 03:57:37 +0000
> Commit:     Greg Lehey <grog@FreeBSD.org>
> CommitDate: 2022-03-28 03:57:37 +0000
>
>      Describe modern time zone handling.
>      Reviewed by:    peterj@
>      MFC after:      2 weeks
That's probably a typo, but it is a good idea to leave an empty line after the first line. Otherwise 
Git tooling thinks all the lines belong to the title of the commit message and it makes for a really 
long email subject. ;)
> ---
>   bin/date/date.1 | 94 ++++++++++++++++++++++++++++++++++++++++++++++++++-------
>   1 file changed, 83 insertions(+), 11 deletions(-)
>
> diff --git a/bin/date/date.1 b/bin/date/date.1
> index 0aaae1614327..e4aad28c7d81 100644
> --- a/bin/date/date.1
> +++ b/bin/date/date.1
> @@ -195,6 +195,13 @@ Print the date and time of the last modification of
>   Display or set the date in
>   .Tn UTC
>   (Coordinated Universal) time.
> +By default
> +.Nm
> +displays the time in the time zone described by
> +.Pa /etc/localtime
> +or the
> +.Ev TZ
> +environment variable.
>   .It Xo
>   .Fl v
>   .Sm off
> @@ -337,10 +344,61 @@ Seconds, a number from 0 to 60
>   .Pp
>   Everything but the minutes is optional.
>   .Pp
> -Time changes for Daylight Saving Time, standard time, leap seconds,
> +.Nm
> +understands the time zone definitions in the
> +.Nm tzdata
> +package located in
> +.Pa /usr/share/zoneinfo .
> +This requires the kernel clock to be set to UTC.
> +Time changes for Daylight Saving Time, standard time, leap seconds
>   and leap years are handled automatically.
> +.Pp
> +There are two ways to specify the time zone:
> +.Pp
> +If the file or symlink
> +.Pa /etc/localtime
> +exists, it is interpreted as a time zone definition file, usually in
> +the directory hierarchy
> +.Pa /usr/share/zoneinfo ,
> +which contains the time zone definitions from the
> +.Nm tzdata
> +package.
> +.Pp
> +If the environment variable
> +.Ev TZ
> +is set, its value is interpreted as the name of a time zone definition
> +file, either an absolute path or a relative path to a time zone
> +definition in
> +.Pa /usr/share/zoneinfo .
> +The
> +.Ev TZ
> +variable overrides
> +.Pa /etc/localtime .
> +.Pp
> +If the time zone definition file is invalid,
> +.Nm
> +silently reverts to UTC.
> +.Pp
> +Previous versions of
> +.Nm
> +included the
> +.Fl d
> +(set daylight saving time flag) and
> +.Fl t
> +(set negative time zone offset) options, but these details are now
> +handled automatically by
> +.Nm tzdata .
This should be Sy instead of Nm. From what I understand, Nm should be used only when referring to 
the subject of the manual page (in this case, "date").
> +Modern offsets are positive for time zones ahead of UTC and negative
> +for time zones behind UTC, but like the obsolete
> +.Nm t
Nm should be Fl.
> +option, the
> +.Nm tzdata
I'd change Nm to Sy.
> +files in the subdirectory
> +.Pa /usr/share/zoneinfo/Etc
> +still use an older convention where times ahead of UTC are considered
> +negative.
>   .Sh ENVIRONMENT
> -The following environment variables affect the execution of
> +The following environment variable affects the execution of
>   .Nm :
>   .Bl -tag -width Ds
>   .It Ev TZ
> @@ -350,16 +408,22 @@ The normal format is a pathname relative to
>   For example, the command
>   .Dq TZ=America/Los_Angeles date
>   displays the current time in California.
> +The variable can also specify an absolute path.
>   See
>   .Xr environ 7
>   for more information.
>   .El
>   .Sh FILES
>   .Bl -tag -width /var/log/messages -compact
> -.It Pa /var/log/utx.log
> -record of date resets and time changes
> +.It Pa /etc/localtime
> +Time zone information file for default system time zone.
> +May be omitted, in which case the default time zone is UTC.
> +.It Pa /usr/share/zoneinfo
> +Directory containing time zone information files.
>   .It Pa /var/log/messages
>   record of the user setting the time
> +.It Pa /var/log/utx.log
> +record of date resets and time changes
Perhaps unrelated to this change, but it would be nice to make all descriptions consistent (start 
with a capital letter, finish with a period).
>   .El
>   .Sh EXIT STATUS
>   The
> @@ -463,13 +527,14 @@ If this occurs,
>   .Nm
>   prints:
>   .Ql multiple output formats specified
> -and exits with an error status.
> +and exits with status 1.
I'm not sure if we want to limit ourselves to 1. Perhaps it's better to just say it is non-zero so 
that we can have the flexibility in the future to return different exit codes for different errors.
>   .Sh SEE ALSO
>   .Xr locale 1 ,
>   .Xr gettimeofday 2 ,
>   .Xr getutxent 3 ,
>   .Xr strftime 3 ,
> -.Xr strptime 3
> +.Xr strptime 3 ,
> +.Xr ntpd 8
>   .Rs
>   .%T "TSP: The Time Synchronization Protocol for UNIX 4.3BSD"
>   .%A R. Gusella
> @@ -480,11 +545,9 @@ The
>   .Nm
>   utility is expected to be compatible with
>   .St -p1003.2 .
> -The
> -.Fl f , I , j , r ,
> -and
> -.Fl v
> -options are all extensions to the standard.
> +With the exception of the
> +.Fl u
> +option, all options are extensions to the standard.
>   .Pp
>   The format selected by the
>   .Fl I
> @@ -496,6 +559,15 @@ A
>   command appeared in
>   .At v1 .
>   .Pp
> +A number of options were added and then removed again, including the
> +.Fl d
> +(set DST flag) and
> +.Fl t
> +(set negative time zone offset).
> +Time zones are now handled by the
> +.Nm tzdata

Nm should be Sy.

Ideally, we should create a manual page for tzdata and just use Xr here.

> +package.
> +.Pp
>   The
>   .Fl I
>   flag was added in
>