Re: [PATCH 4/5] tm.3type: describe tm_zone, tm_gmtoff

[Alejandro Colomar <alx.manpages@gmail.com>]

[-- Attachment #1.1: Type: text/plain, Size: 5135 bytes --]

Hi, наб and Branden!

On 7/19/22 03:56, наб wrote:
> FreeBSD timezone(3) is V7 char *timezone(int zone, int dst),
> our documentation would imply it's impossible to service this type of
> system portably
> 
> Indeed, glibc defines them both, and they make more sense for most
> use-cases than trying to use the globals

Great!

> 
> glibc cited for __USE_MISC, tm_zone invalidation is Debian 2.33-7

But I guess it is present in much older glibcs, right?
Otherwise we should add a VERSIONS thingy.

> POSIX cited for XSI marking is Issue 7 TC2
> CSRG CD #2 contains 4.3BSD-Tahoe with both members
> 
> This also fixes the multiple lies in man-pages 5.10 localtime(3),
> which says only:
>      The glibc version of struct tm has additional fields
>          const char *tm_zone;      /* Timezone abbreviation */
>      defined when _BSD_SOURCE was set before including <time.h>.
>      This is a BSD extension, present in 4.3BSD-Reno.

Did you forget that removal of lies?  I don't see it in the patch.
> 
> Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
> ---
>   man3/tm.3type | 45 +++++++++++++++++++++++++++++++++++++++++++++
>   1 file changed, 45 insertions(+)
> 
> diff --git a/man3/tm.3type b/man3/tm.3type
> index 1931d890d..8b6f8d9bf 100644
> --- a/man3/tm.3type
> +++ b/man3/tm.3type
> @@ -25,8 +25,26 @@ Standard C library
>   .BR "    int  tm_yday;" \
>   "   /* Day of the year  [" 0 ", " 365 "] (Jan/01 = " 0 ") */"
>   .BR "    int  tm_isdst;" "  /* Daylight savings flag */"
> +
> +.BR "    long tm_gmtoff;" " /* Seconds East of UTC */"
> +.BR "    char*tm_zone;" "   /* Timezone abbreviation */"

Please add cosmetic whitespace (at least 1 for every member, possibly 2, 
depending on your taste) :)

>   .B };
>   .fi
> +.PP
> +.RS -4
> +Feature Test Macro Requirements for glibc (see
> +.BR feature_test_macros (7)):
> +.RE
> +.PP
> +.IR tm_gmtoff ,
> +.IR tm_zone :
> +.nf
> +.\" Guarded with __USE_MISC:
> +    Since glibc 2.19:
> +        _DEFAULT_SOURCE
> +    Glibc 2.19 and earlier:
> +        _BSD_SOURCE || _SVID_SOURCE
> +.fi
>   .SH DESCRIPTION
>   Describes time, broken down into distinct components.
>   .PP
> @@ -35,6 +53,16 @@ describes wether daylight saving time is in effect at the time described.
>   The value is positive if daylight saving time is in effect,
>   zero if it is not,
>   and negative if the information is not available.
> +.PP
> +.I tm_gmtoff
> +is the difference, in seconds, of the timezone represented by this broken-down time and UTC
> +(this is the reverse of

Could you come up with a more mathematically precise term for "reverse"? 
  What is reverse?  The additive inverse?  Maybe use "additive inverse"? 
  I think "opposite" also has the meaning of additive inverse in maths, 
and it's maybe a simpler term (although additive inverse is more 
precise, IMHO).  But reverse is definitely confusing to me.

> +.BR timezone (3)).
> +.PP
> +.I tm_zone
> +is the equivalent of
> +.BR tzname (3)
> +for the timezone represented by this broken-down time.
>   .SH VERSIONS
>   In C90,
>   .I tm_sec
> @@ -48,10 +76,27 @@ in C99.
>   .SH CONFORMING TO
>   C90 and later;
>   POSIX.1-2001 and later.
> +.PP
> +.IR tm_gmtoff " and " tm_zone
> +originate from 4.3BSD-Tahoe.
>   .SH NOTES
>   .I tm_sec
>   can represent a leap second with the value
>   .BR 60 .
> +.PP
> +.BR timezone (3),
> +as a variable, is an XSI extension \(em some systems provide the V7-compatible

I tend to prefer the em dash to be next to (no whitespace) the enclosed 
clause.  That makes it easier to mentally associate (as in a set of 
parentheses) to the clause.  I'm not sure if it's a thing of mine, or if 
it's standard practise?

> +.\" FreeBSD
> +.BR timezone ()
> +function.
> +The
> +.I tm_gmtoff
> +fields provides an alternative (with the opposite sign) for those systems.
> +.PP
> +.I tm_zone
> +points to potentially-constant static storage and may be overriden on subsequent calls to
> +.BR localtime (3)
> +&a. (this, however, never happens under glibc).

What is "&a."?  Is that documented somewhere?  I didn't know that 
abbreviature.

Keep in mind man-pages(7):
    Use of e.g., i.e., etc., a.k.a., and similar
        In general, the use  of  abbreviations  such  as  "e.g.",
        "i.e.", "etc.", "cf.", and "a.k.a." should be avoided, in
        favor  of  suitable  full  wordings ("for example", "that
        is", "and so on", "compare to", "also known as").

        The only place where such abbreviations may be acceptable
        is in short parenthetical asides (e.g., like this one).

        Always include periods in such  abbreviations,  as  shown
        here.   In  addition,  "e.g." and "i.e." should always be
        followed by a comma.


BTW, if the '.' is not a sentence ending, it might be good to mark it 
with the ineffable \& escape :)

&a.\& (this ...

>   .SH SEE ALSO
>   .BR ctime (3),
>   .BR strftime (3),

-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]