[PATCH 1/5] tm.3type: tfix

[PATCH 1/5] tm.3type: tfix

[наб]

[-- Attachment #1: Type: text/plain, Size: 628 bytes --]

Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
---
 man3/tm.3type | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/man3/tm.3type b/man3/tm.3type
index 28d6208fb..8ae3a531c 100644
--- a/man3/tm.3type
+++ b/man3/tm.3type
@@ -24,7 +24,7 @@ Standard C library
 "   /* Day of the week [" 0 ", " 6 "] (Sunday = " 0 ") */"
 .BR "    int  tm_yday;" \
 "   /* Day of the year [" 0 ", " 365 "] (Jan/01 = " 0 ") */"
-.BR "    int  tm_isdst;" "  /* Daylighgt savings flag */"
+.BR "    int  tm_isdst;" "  /* Daylight savings flag */"
 .B };
 .fi
 .SH DESCRIPTION
-- 
2.30.2


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

[PATCH 2/5] tm.3type: align ranges

[наб]

[-- Attachment #1: Type: text/plain, Size: 1493 bytes --]

This, to me, makes these much more readable

Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
---
 man3/tm.3type | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/man3/tm.3type b/man3/tm.3type
index 8ae3a531c..daf75e2c1 100644
--- a/man3/tm.3type
+++ b/man3/tm.3type
@@ -14,16 +14,16 @@ Standard C library
 .B #include <time.h>
 .PP
 .B struct tm {
-.BR "    int  tm_sec;" "    /* Seconds [" 0 ", " 60 "] */"
-.BR "    int  tm_min;" "    /* Minutes [" 0 ", " 59 "] */"
-.BR "    int  tm_hour;" "   /* Hour [" 0 ", " 23 "] */"
+.BR "    int  tm_sec;" "    /* Seconds          [" 0 ", " 60 "] */"
+.BR "    int  tm_min;" "    /* Minutes          [" 0 ", " 59 "] */"
+.BR "    int  tm_hour;" "   /* Hour             [" 0 ", " 23 "] */"
 .BR "    int  tm_mday;" "   /* Day of the month [" 1 ", " 31 "] */"
-.BR "    int  tm_mon;" "    /* Month [" 0 ", " 11 "] (January = " 0 ") */"
+.BR "    int  tm_mon;" "    /* Month            [" 0 ", " 11 "] (January = " 0 ") */"
 .BR "    int  tm_year;" "   /* Years since 1900 */"
 .BR "    int  tm_wday;" \
-"   /* Day of the week [" 0 ", " 6 "] (Sunday = " 0 ") */"
+"   /* Day of the week  [" 0 ", " 6 "]   (Sunday = " 0 ") */"
 .BR "    int  tm_yday;" \
-"   /* Day of the year [" 0 ", " 365 "] (Jan/01 = " 0 ") */"
+"   /* Day of the year  [" 0 ", " 365 "] (Jan/01 = " 0 ") */"
 .BR "    int  tm_isdst;" "  /* Daylight savings flag */"
 .B };
 .fi
-- 
2.30.2


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

[PATCH 3/5] tm.3type: tm_year is year minus 1900, not since

[наб]

[-- Attachment #1: Type: text/plain, Size: 952 bytes --]

Since only makes sense if the year represented is after 1900:
how many years have passed since 1900 in... 1410?

Also \fB the constant like elsewhere in the hunk

Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
---
 man3/tm.3type | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/man3/tm.3type b/man3/tm.3type
index daf75e2c1..1931d890d 100644
--- a/man3/tm.3type
+++ b/man3/tm.3type
@@ -19,7 +19,7 @@ Standard C library
 .BR "    int  tm_hour;" "   /* Hour             [" 0 ", " 23 "] */"
 .BR "    int  tm_mday;" "   /* Day of the month [" 1 ", " 31 "] */"
 .BR "    int  tm_mon;" "    /* Month            [" 0 ", " 11 "] (January = " 0 ") */"
-.BR "    int  tm_year;" "   /* Years since 1900 */"
+.BR "    int  tm_year;" "   /* Year minus " 1900 " */"
 .BR "    int  tm_wday;" \
 "   /* Day of the week  [" 0 ", " 6 "]   (Sunday = " 0 ") */"
 .BR "    int  tm_yday;" \
-- 
2.30.2


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

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

[наб]

[-- Attachment #1: Type: text/plain, Size: 3047 bytes --]

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

glibc cited for __USE_MISC, tm_zone invalidation is Debian 2.33-7
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.

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 */"
 .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
+.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
+.\" 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).
 .SH SEE ALSO
 .BR ctime (3),
 .BR strftime (3),
-- 
2.30.2


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

[PATCH 5/5] ctime.3: remove struct tm vestigia

[наб]

[-- Attachment #1: Type: text/plain, Size: 1175 bytes --]

Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
---
Funnily enough, I noticed this only when writing the commit message for
the previous patch and attempting to ascertain how much I should
complain about what's in man-pages 5.10 (which has just tm_zone (!)),
so that commit is entirely unrelated to this one, and its text is
entirely unrelated to this page's

 man3/ctime.3 | 15 ---------------
 1 file changed, 15 deletions(-)

diff --git a/man3/ctime.3 b/man3/ctime.3
index d228bdc21..60ee4418d 100644
--- a/man3/ctime.3
+++ b/man3/ctime.3
@@ -356,21 +356,6 @@ In many implementations, including glibc, a 0 in
 .I tm_mday
 is interpreted as meaning the last day of the preceding month.
 .PP
-The glibc version of \fIstruct tm\fP has additional fields
-.PP
-.in +4n
-.EX
-long tm_gmtoff;           /* Seconds east of UTC */
-const char *tm_zone;      /* Timezone abbreviation */
-.EE
-.in
-.PP
-defined when
-.B _BSD_SOURCE
-was set before including
-.IR <time.h> .
-This is a BSD extension, present in 4.3BSD-Reno.
-.PP
 According to POSIX.1-2001,
 .BR localtime ()
 is required to behave as though
-- 
2.30.2

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

Re: [PATCH 1/5] tm.3type: tfix

[Alejandro Colomar]

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

Hi наб!

On 7/19/22 03:56, наб wrote:
> Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>

Patch applied.

Thanks,

Alex

> ---
>   man3/tm.3type | 2 +-
>   1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/man3/tm.3type b/man3/tm.3type
> index 28d6208fb..8ae3a531c 100644
> --- a/man3/tm.3type
> +++ b/man3/tm.3type
> @@ -24,7 +24,7 @@ Standard C library
>   "   /* Day of the week [" 0 ", " 6 "] (Sunday = " 0 ") */"
>   .BR "    int  tm_yday;" \
>   "   /* Day of the year [" 0 ", " 365 "] (Jan/01 = " 0 ") */"
> -.BR "    int  tm_isdst;" "  /* Daylighgt savings flag */"
> +.BR "    int  tm_isdst;" "  /* Daylight savings flag */"
>   .B };
>   .fi
>   .SH DESCRIPTION

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

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

Re: [PATCH 2/5] tm.3type: align ranges

[Alejandro Colomar]

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

Hi наб,

On 7/19/22 03:56, наб wrote:
> This, to me, makes these much more readable
> 
> Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>

I like the concept of the commit, but I wonder if we can do it in a 
better way.  I was wondering specifically about moving the ranges to 
before the short description, so that they would be aligned naturally, 
without needing so much whitespace.

What would you prefer?

Rendered:

[
SYNOPSIS
        #include <time.h>

        struct tm {
            int  tm_sec;    /* [0, 60] Seconds */
            int  tm_min;    /* [0, 59] Minutes */
            int  tm_hour;   /* [0, 23] Hour */
            int  tm_mday;   /* [1, 31] Day of the month */
            int  tm_mon;    /* [0, 11] Month (January = 0) */
            int  tm_year;   /* Years since 1900 */
            int  tm_wday;   /* [0, 6] Day of the week (Sunday = 0) */
            int  tm_yday;   /* [0, 365] Day of the year (Jan/01 = 0) */
            int  tm_isdst;  /* Daylight savings flag */
        };
]

Cheers,

Alex

> ---
>   man3/tm.3type | 12 ++++++------
>   1 file changed, 6 insertions(+), 6 deletions(-)
> 
> diff --git a/man3/tm.3type b/man3/tm.3type
> index 8ae3a531c..daf75e2c1 100644
> --- a/man3/tm.3type
> +++ b/man3/tm.3type
> @@ -14,16 +14,16 @@ Standard C library
>   .B #include <time.h>
>   .PP
>   .B struct tm {
> -.BR "    int  tm_sec;" "    /* Seconds [" 0 ", " 60 "] */"
> -.BR "    int  tm_min;" "    /* Minutes [" 0 ", " 59 "] */"
> -.BR "    int  tm_hour;" "   /* Hour [" 0 ", " 23 "] */"
> +.BR "    int  tm_sec;" "    /* Seconds          [" 0 ", " 60 "] */"
> +.BR "    int  tm_min;" "    /* Minutes          [" 0 ", " 59 "] */"
> +.BR "    int  tm_hour;" "   /* Hour             [" 0 ", " 23 "] */"
>   .BR "    int  tm_mday;" "   /* Day of the month [" 1 ", " 31 "] */"
> -.BR "    int  tm_mon;" "    /* Month [" 0 ", " 11 "] (January = " 0 ") */"
> +.BR "    int  tm_mon;" "    /* Month            [" 0 ", " 11 "] (January = " 0 ") */"
>   .BR "    int  tm_year;" "   /* Years since 1900 */"
>   .BR "    int  tm_wday;" \
> -"   /* Day of the week [" 0 ", " 6 "] (Sunday = " 0 ") */"
> +"   /* Day of the week  [" 0 ", " 6 "]   (Sunday = " 0 ") */"
>   .BR "    int  tm_yday;" \
> -"   /* Day of the year [" 0 ", " 365 "] (Jan/01 = " 0 ") */"
> +"   /* Day of the year  [" 0 ", " 365 "] (Jan/01 = " 0 ") */"
>   .BR "    int  tm_isdst;" "  /* Daylight savings flag */"
>   .B };
>   .fi

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

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

Re: [PATCH 3/5] tm.3type: tm_year is year minus 1900, not since

[Alejandro Colomar]

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



On 7/19/22 03:56, наб wrote:
> Since only makes sense if the year represented is after 1900:
> how many years have passed since 1900 in... 1410?
> 
> Also \fB the constant like elsewhere in the hunk
> 
> Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>

Patch applied.

Thanks,

Alex

> ---
>   man3/tm.3type | 2 +-
>   1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/man3/tm.3type b/man3/tm.3type
> index daf75e2c1..1931d890d 100644
> --- a/man3/tm.3type
> +++ b/man3/tm.3type
> @@ -19,7 +19,7 @@ Standard C library
>   .BR "    int  tm_hour;" "   /* Hour             [" 0 ", " 23 "] */"
>   .BR "    int  tm_mday;" "   /* Day of the month [" 1 ", " 31 "] */"
>   .BR "    int  tm_mon;" "    /* Month            [" 0 ", " 11 "] (January = " 0 ") */"
> -.BR "    int  tm_year;" "   /* Years since 1900 */"
> +.BR "    int  tm_year;" "   /* Year minus " 1900 " */"
>   .BR "    int  tm_wday;" \
>   "   /* Day of the week  [" 0 ", " 6 "]   (Sunday = " 0 ") */"
>   .BR "    int  tm_yday;" \

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

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

Re: [PATCH 3/5] tm.3type: tm_year is year minus 1900, not since

[Alejandro Colomar]

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

Hi наб,

On 7/19/22 03:56, наб wrote:
> Since only makes sense if the year represented is after 1900:
> how many years have passed since 1900 in... 1410?

When I wrote it, I thought it would be more obvious to use the "since" 
syntax, since for years after 1900 it's very intuitive.  I didn't 
consider that for negative numbers it would be very unintuitive :/

Thanks!

Alex

> 
> Also \fB the constant like elsewhere in the hunk
> 
> Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>

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

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

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

[Alejandro Colomar]

[-- 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 --]

Re: [PATCH 5/5] ctime.3: remove struct tm vestigia

[Alejandro Colomar]

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

On 7/19/22 03:58, наб wrote:
> Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
> ---
> Funnily enough, I noticed this only when writing the commit message for
> the previous patch and attempting to ascertain how much I should
> complain about what's in man-pages 5.10 (which has just tm_zone (!)),
> so that commit is entirely unrelated to this one, and its text is
> entirely unrelated to this page's

Ahh, I see that's here.
Maybe rewrite the previous commit message?
I'll hold applying this patch.

Thanks,

Alex

> 
>   man3/ctime.3 | 15 ---------------
>   1 file changed, 15 deletions(-)
> 
> diff --git a/man3/ctime.3 b/man3/ctime.3
> index d228bdc21..60ee4418d 100644
> --- a/man3/ctime.3
> +++ b/man3/ctime.3
> @@ -356,21 +356,6 @@ In many implementations, including glibc, a 0 in
>   .I tm_mday
>   is interpreted as meaning the last day of the preceding month.
>   .PP
> -The glibc version of \fIstruct tm\fP has additional fields
> -.PP
> -.in +4n
> -.EX
> -long tm_gmtoff;           /* Seconds east of UTC */
> -const char *tm_zone;      /* Timezone abbreviation */
> -.EE
> -.in
> -.PP
> -defined when
> -.B _BSD_SOURCE
> -was set before including
> -.IR <time.h> .
> -This is a BSD extension, present in 4.3BSD-Reno.
> -.PP
>   According to POSIX.1-2001,
>   .BR localtime ()
>   is required to behave as though

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

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

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

[Alejandro Colomar]

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



On 7/19/22 14:17, Alejandro Colomar wrote:
> 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) :)

BTW, since this commit is already adding a lot of stuff, I prefer if you 
add the whitespace in a separate commit.

Thanks,

Alex


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

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

Re: [PATCH 2/5] tm.3type: align ranges

[наб]

[-- Attachment #1: Type: text/plain, Size: 2639 bytes --]

On Tue, Jul 19, 2022 at 01:44:22PM +0200, Alejandro Colomar wrote:
> Hi наб,
> 
> On 7/19/22 03:56, наб wrote:
> > This, to me, makes these much more readable
> > 
> > Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
> 
> I like the concept of the commit, but I wonder if we can do it in a better
> way.  I was wondering specifically about moving the ranges to before the
> short description, so that they would be aligned naturally, without needing
> so much whitespace.
> 
> What would you prefer?

I think that either of
  int         tm_sec;    /* Seconds          [0, 60] */
  int         tm_min;    /* Minutes          [0, 59] */
  int         tm_hour;   /* Hour             [0, 23] */
  int         tm_mday;   /* Day of the month [1, 31] */
  int         tm_mon;    /* Month            [0, 11]  (January = 0) */
  int         tm_year;   /* Year minus 1900 */
  int         tm_wday;   /* Day of the week  [0, 6]   (Sunday = 0) */
  int         tm_yday;   /* Day of the year  [0, 365] (Jan/01 = 0) */
  int         tm_isdst;  /* Daylight savings flag */
or
  int         tm_sec;    /* [0, 60]  Seconds */
  int         tm_min;    /* [0, 59]  Minutes */
  int         tm_hour;   /* [0, 23]  Hour */
  int         tm_mday;   /* [1, 31]  Day of the month */
  int         tm_mon;    /* [0, 11]  Month            (January = 0) */
  int         tm_year;   /*          Year minus 1900 */
  int         tm_wday;   /* [0, 6]   Day of the week  (Sunday = 0) */
  int         tm_yday;   /* [0, 365] Day of the year  (Jan/01 = 0) */
  int         tm_isdst;  /*          Daylight savings flag */
is fine, and other options are strictly worse, but went with the former
because (a) the ranges also align the comment trailers so it's easier to
read and (b) it makes more sense to have "description [domain] [bound]"
than "[domain] description [bound]".

I personally prefer the former but the latter would also be fine.

>            int  tm_sec;    /* [0, 60] Seconds */
>            int  tm_min;    /* [0, 59] Minutes */
>            int  tm_hour;   /* [0, 23] Hour */
>            int  tm_mday;   /* [1, 31] Day of the month */
>            int  tm_mon;    /* [0, 11] Month (January = 0) */
>            int  tm_year;   /* Years since 1900 */
>            int  tm_wday;   /* [0, 6] Day of the week (Sunday = 0) */
>            int  tm_yday;   /* [0, 365] Day of the year (Jan/01 = 0) */
>            int  tm_isdst;  /* Daylight savings flag */
Not columnating at least the domain and description is, to me,
a no-go from a readability stand-point.

Best,
наб

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

Re: [PATCH 2/5] tm.3type: align ranges

[Alejandro Colomar]

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

On 7/19/22 16:14, наб wrote:
> On Tue, Jul 19, 2022 at 01:44:22PM +0200, Alejandro Colomar wrote:
>> Hi наб,
>>
>> On 7/19/22 03:56, наб wrote:
>>> This, to me, makes these much more readable
>>>
>>> Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
>>
>> I like the concept of the commit, but I wonder if we can do it in a better
>> way.  I was wondering specifically about moving the ranges to before the
>> short description, so that they would be aligned naturally, without needing
>> so much whitespace.
>>
>> What would you prefer?
> 
> I think that either of
>    int         tm_sec;    /* Seconds          [0, 60] */
>    int         tm_min;    /* Minutes          [0, 59] */
>    int         tm_hour;   /* Hour             [0, 23] */
>    int         tm_mday;   /* Day of the month [1, 31] */
>    int         tm_mon;    /* Month            [0, 11]  (January = 0) */
>    int         tm_year;   /* Year minus 1900 */
>    int         tm_wday;   /* Day of the week  [0, 6]   (Sunday = 0) */
>    int         tm_yday;   /* Day of the year  [0, 365] (Jan/01 = 0) */
>    int         tm_isdst;  /* Daylight savings flag */
> or
>    int         tm_sec;    /* [0, 60]  Seconds */
>    int         tm_min;    /* [0, 59]  Minutes */
>    int         tm_hour;   /* [0, 23]  Hour */
>    int         tm_mday;   /* [1, 31]  Day of the month */
>    int         tm_mon;    /* [0, 11]  Month            (January = 0) */
>    int         tm_year;   /*          Year minus 1900 */
>    int         tm_wday;   /* [0, 6]   Day of the week  (Sunday = 0) */
>    int         tm_yday;   /* [0, 365] Day of the year  (Jan/01 = 0) */
>    int         tm_isdst;  /*          Daylight savings flag */
> is fine, and other options are strictly worse, but went with the former
> because (a) the ranges also align the comment trailers so it's easier to
> read and (b) it makes more sense to have "description [domain] [bound]"
> than "[domain] description [bound]".
> 
> I personally prefer the former but the latter would also be fine.

Okay, both look good to me, so I'll leave it up to you ;)

> 
>>             int  tm_sec;    /* [0, 60] Seconds */
>>             int  tm_min;    /* [0, 59] Minutes */
>>             int  tm_hour;   /* [0, 23] Hour */
>>             int  tm_mday;   /* [1, 31] Day of the month */
>>             int  tm_mon;    /* [0, 11] Month (January = 0) */
>>             int  tm_year;   /* Years since 1900 */
>>             int  tm_wday;   /* [0, 6] Day of the week (Sunday = 0) */
>>             int  tm_yday;   /* [0, 365] Day of the year (Jan/01 = 0) */
>>             int  tm_isdst;  /* Daylight savings flag */
> Not columnating at least the domain and description is, to me,
> a no-go from a readability stand-point.

Agreed.


Cheers,

Alex

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

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

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

[наб]

[-- Attachment #1: Type: text/plain, Size: 6365 bytes --]

Hi!

On Tue, Jul 19, 2022 at 02:17:15PM +0200, Alejandro Colomar wrote:
> On 7/19/22 03:56, наб wrote:
> > 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.

The fields appear in the glibc git root commit
28f540f45bbacd939bfd07f213bcad2bf730b1bf ("initial import");
the ChangeLog entry for them is
  Mon Apr  6 01:39:07 1992  Roland McGrath  (roland@geech.gnu.ai.mit.edu)
    time/time.h (struct tm): Add `tz_gmtoff', `tz_zone'.
This was 30 years ago, so I don't think we need to version it.

For the macro requirements, blame on the glibc git points to
-- >8 --
@@ -110,8 +110,14 @@ struct tm
   int tm_wday;                 /* Day of week. [0-6] */
   int tm_yday;                 /* Days in year.[0-365] */
   int tm_isdst;                        /* DST.         [-1/0/1]*/
-  long int tm_gmtoff;          /* Seconds west of UTC.  */
+
+#ifdef __USE_BSD
+  long int tm_gmtoff;          /* Seconds east of UTC.  */
   __const char *tm_zone;       /* Timezone abbreviation.  */
+#else
+  long int __tm_gmtoff;                /* Seconds east of UTC.  */
+  __const char *__tm_zone;     /* Timezone abbreviation.  */
+#endif
 };
-- >8 --
from f0f1bf8536fe660cb6230a22694f9b7e6b02605e ("update from main archive
960911"), dated Thu Sep 12 02:51:03 1996 +0000; the relevant message
chunk is
  1996-09-11  Paul Eggert  <eggert@twinsun.com>
    * time/time.h (tm_gmtoff, tm_zone): Prefix with `__' unless
    __USE_BSD; this is required for ANSI C compatibility.
for the origin.

(I realise now __USE_BSD corresponds to just _BSD_SOURCE, which didn't
 match the template I copied, so I updated that for v2).

This was replaced with __USE_MISC in
498afc54dfee41d33ba519f496e96480badace8e ("Combine __USE_BSD and
__USE_SVID into __USE_MISC."):
-- >8 --
@@ -142,7 +142,7 @@ struct tm
   int tm_yday;                 /* Days in year.[0-365] */
   int tm_isdst;                        /* DST.         [-1/0/1]*/

-# ifdef        __USE_BSD
+# ifdef        __USE_MISC
   long int tm_gmtoff;          /* Seconds east of UTC.  */
   const char *tm_zone;         /* Timezone abbreviation.  */
 # else
-- >8 --
which is contained in every tag since glibc-2.20, the relevant part of
which says:
-- >8 --
* The _BSD_SOURCE and _SVID_SOURCE feature test macros are no longer
  supported; they now act the same as _DEFAULT_SOURCE (but generate a
  warning).  Except for cases where _BSD_SOURCE enabled BSD interfaces that
  conflicted with POSIX (support for which was removed in 2.19), the
  interfaces those macros enabled remain available when compiling with
  _GNU_SOURCE defined, with _DEFAULT_SOURCE defined, or without any feature
  test macros defined.
-- >8 --

(I've also updated the f_t_m(7) box to say >=2.20: _D_S, <2.20: _B_S.)

> > This also fixes the multiple lies in man-pages 5.10 localtime(3),
> > which says only:
> Did you forget that removal of lies?  I don't see it in the patch.

I've updated the commit message for v2 to be less misleading,
the removal is in 5/5

> > 
> > 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) :)

Added to match the classic
  long  f1;
  int  *f2;
layout.

> > +.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.

::timezone is seconds West, struct tm::tm_gmtoff is seconds East, so
they have the opposite sign.

I was also not a fan of "reverse", but couldn't come up with a good
english term for it; a skim of a technical terms dictionary points to
  Additive inverse (negation)
  Multiplicative inverse (reciprocal)
but the wiktionary confirms my inkling that "negation" doesn't work here.

"Opposite" may work since we (and POSIX) define this as cur - UTC
(well, POSIX ::timezone in the opposite (hehe) order as UTC - cur),
but that may not be obvious.

"Additive inverse" works, IMO, yeah. Updated.

> > +.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?

Dunno; I'd, personally never seen unspaced dashes in Polish and the vast
majority of modern English and French. Conversely, archaic documents
I've seen tend to prefer dashes touching the surrounding text directly,
so I'd assume this were regional, especially in languages genetically
close to Latin.

Replaced with a colon instead.

> > +.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.

That's an archaic form of "and others" (&a. -> &al. -> et al. -> et alia),
I didn't even notice :v

Replaced with "and similar functions" (this includes localtime_r() and,
depending on the libc, gmtime*(), &c.).

Best,
наб

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

[PATCH v2 1/4] tm.3type: align ranges

[наб]

[-- Attachment #1: Type: text/plain, Size: 1497 bytes --]

This, to me, makes these much more readable

Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
---
 man3/tm.3type | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/man3/tm.3type b/man3/tm.3type
index 5bd34a31e..15284c687 100644
--- a/man3/tm.3type
+++ b/man3/tm.3type
@@ -14,16 +14,16 @@ Standard C library
 .B #include <time.h>
 .PP
 .B struct tm {
-.BR "    int  tm_sec;" "    /* Seconds [" 0 ", " 60 "] */"
-.BR "    int  tm_min;" "    /* Minutes [" 0 ", " 59 "] */"
-.BR "    int  tm_hour;" "   /* Hour [" 0 ", " 23 "] */"
+.BR "    int  tm_sec;" "    /* Seconds          [" 0 ", " 60 "] */"
+.BR "    int  tm_min;" "    /* Minutes          [" 0 ", " 59 "] */"
+.BR "    int  tm_hour;" "   /* Hour             [" 0 ", " 23 "] */"
 .BR "    int  tm_mday;" "   /* Day of the month [" 1 ", " 31 "] */"
-.BR "    int  tm_mon;" "    /* Month [" 0 ", " 11 "] (January = " 0 ") */"
+.BR "    int  tm_mon;" "    /* Month            [" 0 ", " 11 "]  (January = " 0 ") */"
 .BR "    int  tm_year;" "   /* Year minus " 1900 " */"
 .BR "    int  tm_wday;" \
-"   /* Day of the week [" 0 ", " 6 "] (Sunday = " 0 ") */"
+"   /* Day of the week  [" 0 ", " 6 "]   (Sunday = " 0 ") */"
 .BR "    int  tm_yday;" \
-"   /* Day of the year [" 0 ", " 365 "] (Jan/01 = " 0 ") */"
+"   /* Day of the year  [" 0 ", " 365 "] (Jan/01 = " 0 ") */"
 .BR "    int  tm_isdst;" "  /* Daylight savings flag */"
 .B };
 .fi
-- 
2.30.2


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

[PATCH v2 2/4] tm.3type: widen member alignment to take up to const char *

[наб]

[-- Attachment #1: Type: text/plain, Size: 1739 bytes --]

This lets us take const char *tm_zone.

Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
---
 man3/tm.3type | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/man3/tm.3type b/man3/tm.3type
index 15284c687..78e05a41a 100644
--- a/man3/tm.3type
+++ b/man3/tm.3type
@@ -14,17 +14,17 @@ Standard C library
 .B #include <time.h>
 .PP
 .B struct tm {
-.BR "    int  tm_sec;" "    /* Seconds          [" 0 ", " 60 "] */"
-.BR "    int  tm_min;" "    /* Minutes          [" 0 ", " 59 "] */"
-.BR "    int  tm_hour;" "   /* Hour             [" 0 ", " 23 "] */"
-.BR "    int  tm_mday;" "   /* Day of the month [" 1 ", " 31 "] */"
-.BR "    int  tm_mon;" "    /* Month            [" 0 ", " 11 "]  (January = " 0 ") */"
-.BR "    int  tm_year;" "   /* Year minus " 1900 " */"
-.BR "    int  tm_wday;" \
+.BR "    int         tm_sec;" "    /* Seconds          [" 0 ", " 60 "] */"
+.BR "    int         tm_min;" "    /* Minutes          [" 0 ", " 59 "] */"
+.BR "    int         tm_hour;" "   /* Hour             [" 0 ", " 23 "] */"
+.BR "    int         tm_mday;" "   /* Day of the month [" 1 ", " 31 "] */"
+.BR "    int         tm_mon;" "    /* Month            [" 0 ", " 11 "]  (January = " 0 ") */"
+.BR "    int         tm_year;" "   /* Year minus " 1900 " */"
+.BR "    int         tm_wday;" \
 "   /* Day of the week  [" 0 ", " 6 "]   (Sunday = " 0 ") */"
-.BR "    int  tm_yday;" \
+.BR "    int         tm_yday;" \
 "   /* Day of the year  [" 0 ", " 365 "] (Jan/01 = " 0 ") */"
-.BR "    int  tm_isdst;" "  /* Daylight savings flag */"
+.BR "    int         tm_isdst;" "  /* Daylight savings flag */"
 .B };
 .fi
 .SH DESCRIPTION
-- 
2.30.2


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

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

[наб]

[-- Attachment #1: Type: text/plain, Size: 2880 bytes --]

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

glibc cited for __USE_MISC, tm_zone invalidation is Debian 2.33-7
POSIX cited for XSI marking is Issue 7 TC2
CSRG CD #2 contains 4.3BSD-Tahoe with both members

We currently ship an outdated (and factually misleading) version
of this description in ctime.3

Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
---
 man3/tm.3type | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/man3/tm.3type b/man3/tm.3type
index 78e05a41a..e7e39cc5c 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 "    const char *tm_zone;" "   /* Timezone abbreviation */"
 .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.20:
+        _DEFAULT_SOURCE
+    Glibc 2.20 and earlier:
+        _BSD_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 additive inverse of
+.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,30 @@ 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 (where
+.I tm_zone
+is a
+.IR "char *" ).
 .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: some systems provide the V7-compatible
+.\" FreeBSD
+.BR timezone ()
+function.
+The
+.I tm_gmtoff
+field provides an alternative (with the opposite sign) for those systems.
+.PP
+.I tm_zone
+points to static storage and may be overriden on subsequent calls to
+.BR localtime (3)
+and similar functions (this, however, never happens under glibc).
 .SH SEE ALSO
 .BR ctime (3),
 .BR strftime (3),
-- 
2.30.2


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

[PATCH v2 4/4] ctime.3: remove struct tm vestigia

[наб]

[-- Attachment #1: Type: text/plain, Size: 861 bytes --]

Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
---
 man3/ctime.3 | 15 ---------------
 1 file changed, 15 deletions(-)

diff --git a/man3/ctime.3 b/man3/ctime.3
index d228bdc21..60ee4418d 100644
--- a/man3/ctime.3
+++ b/man3/ctime.3
@@ -356,21 +356,6 @@ In many implementations, including glibc, a 0 in
 .I tm_mday
 is interpreted as meaning the last day of the preceding month.
 .PP
-The glibc version of \fIstruct tm\fP has additional fields
-.PP
-.in +4n
-.EX
-long tm_gmtoff;           /* Seconds east of UTC */
-const char *tm_zone;      /* Timezone abbreviation */
-.EE
-.in
-.PP
-defined when
-.B _BSD_SOURCE
-was set before including
-.IR <time.h> .
-This is a BSD extension, present in 4.3BSD-Reno.
-.PP
 According to POSIX.1-2001,
 .BR localtime ()
 is required to behave as though
-- 
2.30.2

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

Re: [PATCH v2 2/4] tm.3type: widen member alignment to take up to const char *

[Alejandro Colomar]

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



On 7/19/22 17:35, наб wrote:
> This lets us take const char *tm_zone.
> 
> Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>

Patches v2 1/4 and 2/4 applied.

Thanks,

Alex

> ---
>   man3/tm.3type | 18 +++++++++---------
>   1 file changed, 9 insertions(+), 9 deletions(-)
> 
> diff --git a/man3/tm.3type b/man3/tm.3type
> index 15284c687..78e05a41a 100644
> --- a/man3/tm.3type
> +++ b/man3/tm.3type
> @@ -14,17 +14,17 @@ Standard C library
>   .B #include <time.h>
>   .PP
>   .B struct tm {
> -.BR "    int  tm_sec;" "    /* Seconds          [" 0 ", " 60 "] */"
> -.BR "    int  tm_min;" "    /* Minutes          [" 0 ", " 59 "] */"
> -.BR "    int  tm_hour;" "   /* Hour             [" 0 ", " 23 "] */"
> -.BR "    int  tm_mday;" "   /* Day of the month [" 1 ", " 31 "] */"
> -.BR "    int  tm_mon;" "    /* Month            [" 0 ", " 11 "]  (January = " 0 ") */"
> -.BR "    int  tm_year;" "   /* Year minus " 1900 " */"
> -.BR "    int  tm_wday;" \
> +.BR "    int         tm_sec;" "    /* Seconds          [" 0 ", " 60 "] */"
> +.BR "    int         tm_min;" "    /* Minutes          [" 0 ", " 59 "] */"
> +.BR "    int         tm_hour;" "   /* Hour             [" 0 ", " 23 "] */"
> +.BR "    int         tm_mday;" "   /* Day of the month [" 1 ", " 31 "] */"
> +.BR "    int         tm_mon;" "    /* Month            [" 0 ", " 11 "]  (January = " 0 ") */"
> +.BR "    int         tm_year;" "   /* Year minus " 1900 " */"
> +.BR "    int         tm_wday;" \
>   "   /* Day of the week  [" 0 ", " 6 "]   (Sunday = " 0 ") */"
> -.BR "    int  tm_yday;" \
> +.BR "    int         tm_yday;" \
>   "   /* Day of the year  [" 0 ", " 365 "] (Jan/01 = " 0 ") */"
> -.BR "    int  tm_isdst;" "  /* Daylight savings flag */"
> +.BR "    int         tm_isdst;" "  /* Daylight savings flag */"
>   .B };
>   .fi
>   .SH DESCRIPTION

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

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

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

[Alejandro Colomar]

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

On 7/19/22 17:35, наб wrote:
> ---
>   man3/tm.3type | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
>   1 file changed, 48 insertions(+)
> 
> diff --git a/man3/tm.3type b/man3/tm.3type
> index 78e05a41a..e7e39cc5c 100644
> --- a/man3/tm.3type
> +++ b/man3/tm.3type
[...]
> @@ -48,10 +76,30 @@ in C99.
>   .SH CONFORMING TO
>   C90 and later;
>   POSIX.1-2001 and later.
> +.PP
> +.IR tm_gmtoff " and " tm_zone

I prefer one identifier per line:

.I foo
and
.I bar

> +originate from 4.3BSD-Tahoe (where
> +.I tm_zone
> +is a
> +.IR "char *" ).
>   .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: some systems provide the V7-compatible
> +.\" FreeBSD
> +.BR timezone ()
> +function.
> +The
> +.I tm_gmtoff
> +field provides an alternative (with the opposite sign) for those systems.
> +.PP
> +.I tm_zone
> +points to static storage and may be overriden on subsequent calls to
> +.BR localtime (3)
> +and similar functions (this, however, never happens under glibc).

If you reorder it, you can remove a coma:

however, this never ...

>   .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 --]

Re: [PATCH v2 4/4] ctime.3: remove struct tm vestigia

[Alejandro Colomar]

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

наб, I think this would need a bit more of a commit message, even if the 
previous one already hints that this removal will happen.

Cheers,

Alex

On 7/19/22 17:35, наб wrote:
> Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
> ---
>   man3/ctime.3 | 15 ---------------
>   1 file changed, 15 deletions(-)
> 
> diff --git a/man3/ctime.3 b/man3/ctime.3
> index d228bdc21..60ee4418d 100644
> --- a/man3/ctime.3
> +++ b/man3/ctime.3
> @@ -356,21 +356,6 @@ In many implementations, including glibc, a 0 in
>   .I tm_mday
>   is interpreted as meaning the last day of the preceding month.
>   .PP
> -The glibc version of \fIstruct tm\fP has additional fields
> -.PP
> -.in +4n
> -.EX
> -long tm_gmtoff;           /* Seconds east of UTC */
> -const char *tm_zone;      /* Timezone abbreviation */
> -.EE
> -.in
> -.PP
> -defined when
> -.B _BSD_SOURCE
> -was set before including
> -.IR <time.h> .
> -This is a BSD extension, present in 4.3BSD-Reno.
> -.PP
>   According to POSIX.1-2001,
>   .BR localtime ()
>   is required to behave as though

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

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

[PATCH v3 1/2] tm.3type: describe tm_zone, tm_gmtoff

[наб]

[-- Attachment #1: Type: text/plain, Size: 2883 bytes --]

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

glibc cited for __USE_MISC, tm_zone invalidation is Debian 2.33-7
POSIX cited for XSI marking is Issue 7 TC2
CSRG CD #2 contains 4.3BSD-Tahoe with both members

We currently ship an outdated (and factually misleading) version
of this description in ctime.3

Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
---
 man3/tm.3type | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)

diff --git a/man3/tm.3type b/man3/tm.3type
index 78e05a41a..c23fc023e 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 "    const char *tm_zone;" "   /* Timezone abbreviation */"
 .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.20:
+        _DEFAULT_SOURCE
+    Glibc 2.20 and earlier:
+        _BSD_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 additive inverse of
+.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,32 @@ in C99.
 .SH CONFORMING TO
 C90 and later;
 POSIX.1-2001 and later.
+.PP
+.I tm_gmtoff
+and
+.I tm_zone
+originate from 4.3BSD-Tahoe (where
+.I tm_zone
+is a
+.IR "char *" ).
 .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: some systems provide the V7-compatible
+.\" FreeBSD
+.BR timezone ()
+function.
+The
+.I tm_gmtoff
+field provides an alternative (with the opposite sign) for those systems.
+.PP
+.I tm_zone
+points to static storage and may be overriden on subsequent calls to
+.BR localtime (3)
+and similar functions (however, this never happens under glibc).
 .SH SEE ALSO
 .BR ctime (3),
 .BR strftime (3),
-- 
2.30.2


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

[PATCH v3 2/2] ctime.3: remove struct tm vestigia

[наб]

[-- Attachment #1: Type: text/plain, Size: 969 bytes --]

struct tm lives in tm.3type, and we now describe both of these fields,
in detail and correctly, therein

Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
---
 man3/ctime.3 | 15 ---------------
 1 file changed, 15 deletions(-)

diff --git a/man3/ctime.3 b/man3/ctime.3
index d228bdc21..60ee4418d 100644
--- a/man3/ctime.3
+++ b/man3/ctime.3
@@ -356,21 +356,6 @@ In many implementations, including glibc, a 0 in
 .I tm_mday
 is interpreted as meaning the last day of the preceding month.
 .PP
-The glibc version of \fIstruct tm\fP has additional fields
-.PP
-.in +4n
-.EX
-long tm_gmtoff;           /* Seconds east of UTC */
-const char *tm_zone;      /* Timezone abbreviation */
-.EE
-.in
-.PP
-defined when
-.B _BSD_SOURCE
-was set before including
-.IR <time.h> .
-This is a BSD extension, present in 4.3BSD-Reno.
-.PP
 According to POSIX.1-2001,
 .BR localtime ()
 is required to behave as though
-- 
2.30.2

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

Re: [PATCH v3 1/2] tm.3type: describe tm_zone, tm_gmtoff

[Alejandro Colomar]

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

Hi наб,

On 7/19/22 20:38, наб 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
> 
> glibc cited for __USE_MISC, tm_zone invalidation is Debian 2.33-7
> POSIX cited for XSI marking is Issue 7 TC2
> CSRG CD #2 contains 4.3BSD-Tahoe with both members
> 
> We currently ship an outdated (and factually misleading) version
> of this description in ctime.3
> 
> Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz> > ---
>   man3/tm.3type | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++
>   1 file changed, 50 insertions(+)
> 
> diff --git a/man3/tm.3type b/man3/tm.3type
> index 78e05a41a..c23fc023e 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 */"
> +

Use .PP.  See man-pages(7):
    Formatting conventions (general)
        Paragraphs should be separated by suitable markers  (usu‐
        ally  either .PP or .IP).  Do not separate paragraphs us‐
        ing blank lines, as this results  in  poor  rendering  in
        some output formats (such as PostScript and PDF).


> +.BR "    long        tm_gmtoff;" " /* Seconds East of UTC */"
> +.BR "    const char *tm_zone;" "   /* Timezone abbreviation */"
>   .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.20:
> +        _DEFAULT_SOURCE
> +    Glibc 2.20 and earlier:
> +        _BSD_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

Heh, as the old kernel coding style used to read,
"The limit on the length of lines is 80 columns and this is a strongly 
preferred limit."

Rationale: I can keep the font size quite big, and still have 2 
terminals in a FullHD screen side by side, with line numbers.

I can still see around 87 characters (a little more than 80),
but that line is too much for me.  If eighty-few characters really 
improve readability, I can accept that, especially for SYNOPSIS, but in 
running text, 80-char is more of a strong limit.

BTW, I just realized the SYNOPSIS moved past my screen on the terminal.
I fixed it.

> +(this is the additive inverse of
> +.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,32 @@ in C99.
>   .SH CONFORMING TO
>   C90 and later;
>   POSIX.1-2001 and later.
> +.PP
> +.I tm_gmtoff
> +and
> +.I tm_zone
> +originate from 4.3BSD-Tahoe (where
> +.I tm_zone
> +is a
> +.IR "char *" ).
>   .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: some systems provide the V7-compatible
> +.\" FreeBSD
> +.BR timezone ()

I've been thinking about if we should put there a section number.
I think we should.  Actually, timezone(3) documents the function in NOTES.

Cheers,

Alex

> +function.
> +The
> +.I tm_gmtoff
> +field provides an alternative (with the opposite sign) for those systems.
> +.PP
> +.I tm_zone
> +points to static storage and may be overriden on subsequent calls to
> +.BR localtime (3)
> +and similar functions (however, this never happens under glibc).
>   .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 --]

Re: [PATCH v3 1/2] tm.3type: describe tm_zone, tm_gmtoff

[наб]

[-- Attachment #1: Type: text/plain, Size: 2692 bytes --]

Hi!

On Tue, Jul 19, 2022 at 10:33:34PM +0200, Alejandro Colomar wrote:
> On 7/19/22 20:38, наб wrote:
> > diff --git a/man3/tm.3type b/man3/tm.3type
> > index 78e05a41a..c23fc023e 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 */"
> > +
> 
> Use .PP.  See man-pages(7):
>    Formatting conventions (general)
>        Paragraphs should be separated by suitable markers  (usu‐
>        ally  either .PP or .IP).  Do not separate paragraphs us‐
>        ing blank lines, as this results  in  poor  rendering  in
>        some output formats (such as PostScript and PDF).

Too used to mdoc(7) in .Bd -literal mode where an empty line is correct
for these. Fixed for v4.

> > @@ -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
> 
> Heh, as the old kernel coding style used to read,
> "The limit on the length of lines is 80 columns and this is a strongly
> preferred limit."
> 
> Rationale: I can keep the font size quite big, and still have 2 terminals in
> a FullHD screen side by side, with line numbers.
> 
> I can still see around 87 characters (a little more than 80),
> but that line is too much for me.  If eighty-few characters really improve
> readability, I can accept that, especially for SYNOPSIS, but in running
> text, 80-char is more of a strong limit.

Sure. Cracked before of for v4.

> > +.PP
> > +.BR timezone (3),
> > +as a variable, is an XSI extension: some systems provide the V7-compatible
> > +.\" FreeBSD
> > +.BR timezone ()
> 
> I've been thinking about if we should put there a section number.
> I think we should.  Actually, timezone(3) documents the function in NOTES.

Disagree: timezone() is /not/ timezone(3).

Our (and XSI) timezone(3) is
  extern long timezone;
whereas the V7-compatible timezone() is
  extern char *timezone(int zone, int dst);
cf. https://www.freebsd.org/cgi/man.cgi?query=timezone&apropos=0&sektion=0&manpath=FreeBSD+13.1-RELEASE+and+Ports&arch=default&format=html

That's why I Xred the first usage (which refers to the variable we
document) and not the second (which refers to a function we don't).

Thoughts?

Best,
наб

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

Re: [PATCH v3 1/2] tm.3type: describe tm_zone, tm_gmtoff

[Alejandro Colomar]

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

Hi!

On 7/19/22 23:36, наб wrote:
>>> +.PP
>>> +.BR timezone (3),
>>> +as a variable, is an XSI extension: some systems provide the V7-compatible
>>> +.\" FreeBSD
>>> +.BR timezone ()
>>
>> I've been thinking about if we should put there a section number.
>> I think we should.  Actually, timezone(3) documents the function in NOTES.
> 
> Disagree: timezone() is /not/ timezone(3).

I understand that timezone() is not _our_ timezone(3).  And that's why I 
still have some doubts.  I thought about using timezone(3BSD), but 
sadly, libbsd doesn't provide the timezone() function.

> 
> Our (and XSI) timezone(3) is
>    extern long timezone;
> whereas the V7-compatible timezone() is
>    extern char *timezone(int zone, int dst);
> cf. https://www.freebsd.org/cgi/man.cgi?query=timezone&apropos=0&sektion=0&manpath=FreeBSD+13.1-RELEASE+and+Ports&arch=default&format=html
> 
> That's why I Xred the first usage (which refers to the variable we
> document) and not the second (which refers to a function we don't).

But we do document BSD's timezone() in our timezone(3) (although that 
documentation could probably be improved):


$ man timezone | sed -n '/NOTES/,/^$/p'
NOTES
        4.3BSD had a function char *timezone(zone, dst) that  re‐
        turned  the  name  of  the  timezone corresponding to its
        first argument (minutes West of UTC).  If the second  ar‐
        gument  was  0, the standard name was used, otherwise the
        daylight saving time version.

Considering also man-pages(7):
        SEE ALSO
               [...]

               Given the distributed, autonomous nature  of  FOSS
               projects  and their documentation, it is sometimes
               necessary—and in many cases desirable—that the SEE
               ALSO section includes references to  manual  pages
               provided by other projects.


I'd say we should .Xr (.MR) it.  Until .MR is widely available, .BR (3) 
is good enough :)

Cheers,

Alex


> 
> Thoughts?
> 
> Best,
> наб

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

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

[PATCH v4 1/2] tm.3type: describe tm_zone, tm_gmtoff

[наб]

[-- Attachment #1: Type: text/plain, Size: 2890 bytes --]

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

glibc cited for __USE_MISC, tm_zone invalidation is Debian 2.33-7
POSIX cited for XSI marking is Issue 7 TC2
CSRG CD #2 contains 4.3BSD-Tahoe with both members

We currently ship an outdated (and factually misleading) version
of this description in ctime.3

Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
---
 man3/tm.3type | 51 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)

diff --git a/man3/tm.3type b/man3/tm.3type
index 4117b36a0..4b98819f9 100644
--- a/man3/tm.3type
+++ b/man3/tm.3type
@@ -26,8 +26,26 @@ Standard C library
 .BR "    int         tm_yday;" \
 "   /* Day of the year  [" 0 ", " 365 "] (Jan/01 = " 0 ") */"
 .BR "    int         tm_isdst;" "  /* Daylight savings flag */"
+.PP
+.BR "    long        tm_gmtoff;" " /* Seconds East of UTC */"
+.BR "    const char *tm_zone;" "   /* Timezone abbreviation */"
 .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.20:
+        _DEFAULT_SOURCE
+    Glibc 2.20 and earlier:
+        _BSD_SOURCE
+.fi
 .SH DESCRIPTION
 Describes time, broken down into distinct components.
 .PP
@@ -36,6 +54,17 @@ 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 additive inverse of
+.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
@@ -49,10 +78,32 @@ in C99.
 .SH CONFORMING TO
 C90 and later;
 POSIX.1-2001 and later.
+.PP
+.I tm_gmtoff
+and
+.I tm_zone
+originate from 4.3BSD-Tahoe (where
+.I tm_zone
+is a
+.IR "char *" ).
 .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: some systems provide the V7-compatible
+.\" FreeBSD
+.BR timezone (3)
+function.
+The
+.I tm_gmtoff
+field provides an alternative (with the opposite sign) for those systems.
+.PP
+.I tm_zone
+points to static storage and may be overriden on subsequent calls to
+.BR localtime (3)
+and similar functions (however, this never happens under glibc).
 .SH SEE ALSO
 .BR ctime (3),
 .BR strftime (3),
-- 
2.30.2


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

[PATCH v4 2/2] ctime.3: remove struct tm vestigia

[наб]

[-- Attachment #1: Type: text/plain, Size: 969 bytes --]

struct tm now lives in tm.3type, and we describe both of these fields,
in detail and correctly, therein

Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
---
 man3/ctime.3 | 15 ---------------
 1 file changed, 15 deletions(-)

diff --git a/man3/ctime.3 b/man3/ctime.3
index d228bdc21..60ee4418d 100644
--- a/man3/ctime.3
+++ b/man3/ctime.3
@@ -356,21 +356,6 @@ In many implementations, including glibc, a 0 in
 .I tm_mday
 is interpreted as meaning the last day of the preceding month.
 .PP
-The glibc version of \fIstruct tm\fP has additional fields
-.PP
-.in +4n
-.EX
-long tm_gmtoff;           /* Seconds east of UTC */
-const char *tm_zone;      /* Timezone abbreviation */
-.EE
-.in
-.PP
-defined when
-.B _BSD_SOURCE
-was set before including
-.IR <time.h> .
-This is a BSD extension, present in 4.3BSD-Reno.
-.PP
 According to POSIX.1-2001,
 .BR localtime ()
 is required to behave as though
-- 
2.30.2

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

Re: [PATCH v4 2/2] ctime.3: remove struct tm vestigia

[Alejandro Colomar]

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

Hi наб!

On 7/20/22 00:36, наб wrote:
> struct tm now lives in tm.3type, and we describe both of these fields,
> in detail and correctly, therein
> 
> Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>

Great job!  Patch set applied!

Thanks,

Alex

> ---
>   man3/ctime.3 | 15 ---------------
>   1 file changed, 15 deletions(-)
> 
> diff --git a/man3/ctime.3 b/man3/ctime.3
> index d228bdc21..60ee4418d 100644
> --- a/man3/ctime.3
> +++ b/man3/ctime.3
> @@ -356,21 +356,6 @@ In many implementations, including glibc, a 0 in
>   .I tm_mday
>   is interpreted as meaning the last day of the preceding month.
>   .PP
> -The glibc version of \fIstruct tm\fP has additional fields
> -.PP
> -.in +4n
> -.EX
> -long tm_gmtoff;           /* Seconds east of UTC */
> -const char *tm_zone;      /* Timezone abbreviation */
> -.EE
> -.in
> -.PP
> -defined when
> -.B _BSD_SOURCE
> -was set before including
> -.IR <time.h> .
> -This is a BSD extension, present in 4.3BSD-Reno.
> -.PP
>   According to POSIX.1-2001,
>   .BR localtime ()
>   is required to behave as though

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

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

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

[G. Branden Robinson]

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

Hi Alex,

At 2022-07-19T14:17:15+0200, Alejandro Colomar wrote:
> Hi, наб and Branden!

I'm not exactly sure what you wanted me to comment on in this patch
submission.

Keep in mind that I am a bear of little brain--please be clear what it
is you're asking of me.  ;-)

I will assume that it is my *roff/man(7) expertise (such as it is) and
will respond on that assumption.

I will also comment on English usage because I can't help myself.

> > diff --git a/man3/tm.3type b/man3/tm.3type

Oh, bother.  Bash autocompletion for "man" on my Debian bullseye is too
dumb to recognize this new man page suffix.  I trust someone reading
this is aware of the problem and is fixing it for the next Debian
release.  (Has someone filed this as a bug with the Debian BTS?)

Other distributions may have similar concerns.

> > 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) :)

Hmmm.  I'm attaching a screenshot of Okular's rendering of the current
state of tm(3type) in the Linux man-pages Git repository to PostScript.

Recall the advice in groff's Texinfo manual.  This is from groff 1.22.4.

5.1.6 Input Conventions
-----------------------

[...]
   * Do not try to do any formatting in a WYSIWYG manner (i.e., don't
     try using spaces to get proper indentation).

Synopses in man pages, whether for section [168] commands or section
[23] C function calls or data types, are not typically set in a
monospaced typeface, nor do I think they should be.  A proportional
typeface generally looks better.

The price of that improved appearance is that the use of sequences of
spaces to get columnar alignment breaks as soon as there is variation in
the content.

The traditional solution to this problem in the *roff language is to set
tab stops.  However, man-pages(7) calls out tab stop manipulation as
unportable man(7) usage.

       *  Example programs should be laid out according  to  Kernighan
          and  Ritchie style, with 4‐space indents.  (Avoid the use of
          TAB characters in source code!)

Now, section 2 and 3 synopses are not _example program_ source code, so
a defense of tab usage could be made here, but a man page author simply
trying to get their stuff documented could be forgiven for feeling that
drawing such a distinction is hair-splitting.

Using spaces is, however, in my opinion, worse simply due to the effect
on rendered output for everything that isn't a terminal.

There are a few ways to address this issue.

A. Don't worry about it and let HTML/PostScript/PDF output look ugly.

B. Stick synopses, at least for section 2 and 3 man pages, in EX/EE
   blocks, which switch the typeface to Courier on typesetting output
   devices (which includes HTML if the groff project fixes grohtml to
   change font families--it's _supposed_ to, but something broke a long
   time ago).  My recollection is that Michael Kerrisk opposed this
   practice.  I too don't think it's a great idea; the average glyph
   width is lower in proportional fonts, so using it, you can fit more
   content on an output line.

C. Use tabs anyway.  For results that will actually get what you want,
   you will need to set the tab stops to ensure they're wide enough to
   achieve the desired alignment.  The use of custom tab stops requires
   invoking the `ta` request, and this is warned against in the
   "Portability" section of groff_man(7) (to be part of
   groff_man_style(7) in groff 1.23).  But by invoking the `nf` and `fi`
   requests for other reasons, this project's pages have already crossed
   that bridge.

C1. Actually selecting values for the tab stops can be tedious.  You can
    hard-code measurements, but it will be hard to maintain consistency
    among contributors (will you use ens, ems, inches, or centimeters as
    the scaling unit?) and, much worse, the size of the rendered
    typeface can vary.  groff_man(7) explicitly countenances selection
    of a 10-, 11-, or 12-point typefaces.  At present, no means of
    changing the default font family for body text is exposed, but it
    might be in the future.  So I expect the temptation will be to set
    tab stops for 10-point Times (but see below), which will lead to
    ugly results for other family/size selections.

C2. Clever roff writers (sometimes too clever) reach for the \w escape
    sequence to overcome this problem.  So instead of hard-coding tab
    stop lengths, they have the formatter compute them based on sample
    inputs.  For the page under discussion, this practice would lead to
    requests that look like the following.

    .ta \w'char*' \w'tm_gmtoff'

    What's happening here is that the "longest" item within each tab
    stop is getting its length computed, and those computed lengths used
    as the tab stop values.  In practice this won't quite do because it
    will leave no space between the items in the event the same row has
    two of the longest column entries adjacent, so you more often see
    something like this.

    .ta \w'char*'+1n \w'tm_gmtoff'+1n

    This ensures that the tab stops have extra one "en" of space between
    them.  It doesn't suck, but at this point your man page renderer
    needs to be sophisticated enough to include an arithmetic expression
    evaluator.  This provokes grumbles from folks like Ingo who maintain
    non-roff man page formatters.

    It is true that we could add a macro to man(7) that conceals a bit
    of this complexity.  Like this.

    .TA char gmtoff

    This certainly looks much cleaner, and in fact it closely resembles
    Texinfo's @multitable command.  But it is just a mask over the
    `ta` request of frightening appearance above, not a silver bullet.

C3. The above has the problem that it relies upon the writer to know
    which pieces of text between the tab stops are the longest.  This
    sounds like an obvious thing that no one would ever screw up.
    I think that assumption would be swiftly overturned.

    There are two big problems.  The first is maintenance.  Considering
    potential applications in Linux man-pages, you will often have
    situations where someone adds a new function or struct member to a
    synopsis.  A contributor may already be at the limit of their man(7)
    knowledge.  They may not look far enough up the page to see the `ta`
    request, may not understand it, and may not think to consider that
    they've just added a new longest item, and thus need to update that
    `ta` request.  Because that request may be outside the scope of the
    diff context, it will be easy for reviewers to overlook, too.

    The other issue is more subtle.  I predict that contributors are
    likely to reckon widths in terms of character cells, not the
    horizontal measurement of rendered text.  Because a proportional
    font is used for rendering, the results can be surprising.

	$ groff
	.nr m \w'mmm'
	.nr i \w'iiii'
	.tm m=\nm, i=\ni
	m=23340, i=11120

    In 10-point Times, "mmm" is over twice as wide as "iiii".  I dare
    say few man page contributors are going to think of this.  Not
    having Times roman's font metrics and a full adder operating in
    their heads when they're thinking about documenting an API, they
    will frequently fail to correctly select the "longest" content
    within a particular tab stop for an argument to \w in a `ta`
    request.

    Sorting this kind of thing out is a pain.  Why don't we have
    something that recognizes when we're using a series of lines with
    tabs, then reads them all and computes the tab stops necessary to
    separate them nicely?

D. Congratulations, you've discovered tbl(1).[1]

I guess my advice is to choose your poison.  I'll advise as best I can.

> 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?

"Spacing around an em dash varies. Most newspapers insert a space before
and after the dash, and many popular magazines do the same, but most
books and journals omit spacing, closing whatever comes before and after
the em dash right up next to it. This website prefers the latter, its
style requiring the closely held em dash in running text."

https://www.merriam-webster.com/words-at-play/em-dash-en-dash-how-to-use

In the groff man pages, I too "close up" any space around em dashes, but
I freely admit that this (1) doesn't look all that great in terminal
rendering [it too closely resembles other dashes--a "fullwidth" dash
taking two character cells would be preferable on purely esthetic
grounds, and probably a nightmare to get terminal emulators to cope
with] and (2) it frustrates my input style; since I don't want to use
the `\c` escape sequence, I end up putting the words immediately outside
the em-dashed aside on the "wrong" lines semantically.  Maybe I should
just get over my allergy to `\c` now that I understand how it
works.[citation needed]

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

Having seen наб's reply, it seems of a piece with "&c.", which was
in English formerly (ca. 150 years ago) a common abbreviation for the
Latin "et cetera".  Nowadays "etc." has fully supplanted "&c." while
many native English speakers are shaky on what, exactly, it abbreviates,
even spelling it "ect." because that better aligns with English language
phonotactics.

I admit never having seen "&a." before in English writing.  Like
Germans' use of "resp.", it may be a thing non-native speakers assume
"ports" into English, but doesn't.

Regards,
Branden

[1] https://git.savannah.gnu.org/cgit/groff.git/tree/src/preproc/tbl/tbl.1.man

[-- Attachment #1.2: tm.3type.ps.png --]
[-- Type: image/png, Size: 180 bytes --]

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

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

[Alejandro Colomar (man-pages)]

Hi Branden,

On 7/22/22 05:33, G. Branden Robinson wrote:
> Hi Alex,
> 
> At 2022-07-19T14:17:15+0200, Alejandro Colomar wrote:
>> Hi, наб and Branden!
> 
> I'm not exactly sure what you wanted me to comment on in this patch
> submission.
> 
> Keep in mind that I am a bear of little brain--please be clear what it
> is you're asking of me.  ;-)
> 
> I will assume that it is my *roff/man(7) expertise (such as it is) and
> will respond on that assumption.
> 
> I will also comment on English usage because I can't help myself.

You answered all that I thought you would, and even more.  As always, 
you surprise me with great knowledge that I didn't even know I could ask 
for, and that's the main reason I tend to not try to direct your 
answers.  They're always welcome (although sometimes the knowledge is 
too much for me, a novice groff(7) user, to understand it; but I try to).

Thanks!

> 
>>> diff --git a/man3/tm.3type b/man3/tm.3type
> 
> Oh, bother.  Bash autocompletion for "man" on my Debian bullseye is too
> dumb to recognize this new man page suffix.  I trust someone reading
> this is aware of the problem and is fixing it for the next Debian
> release.  (Has someone filed this as a bug with the Debian BTS?)

I don't think it's been reported.  I've detected some unpleasantness, 
but since I also had some unpleasantness with pages in the main 
sections, I didn't know if there was even more of it with subsections.

Was it trying to read a manual page from a relative path?  That's where 
I find a lot of problems, and that's why I always `sudo make install` 
the pages, then read them from the system as usual.  That makes it 
easier.  I improved the Makefile to make that loop experience something 
nice.

Anyway, would you mind reporting the bug you notice and CCing me?

> 
> Other distributions may have similar concerns.
> 
>>> 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) :)
> 
> Hmmm.  I'm attaching a screenshot of Okular's rendering of the current
> state of tm(3type) in the Linux man-pages Git repository to PostScript.

I only see a black 180 bytes image.  Probably not what you expected to send?

Anyway, I used pdfman()[1] to read the page in PDF, and I get your point.


[1]: 
<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/scripts/bash_aliases#n179>

      To use that bash_aliases file, I have the following in my 
.bash_aliases:

if [ -f ~/src/linux/man-pages/man-pages/scripts/bash_aliases ]; then
	. ~/src/linux/man-pages/man-pages/scripts/bash_aliases;
fi;

> 
> Recall the advice in groff's Texinfo manual.  This is from groff 1.22.4.
> 
> 5.1.6 Input Conventions
> -----------------------
> 
> [...]
>     * Do not try to do any formatting in a WYSIWYG manner (i.e., don't
>       try using spaces to get proper indentation).
> 
> Synopses in man pages, whether for section [168] commands or section
> [23] C function calls or data types, are not typically set in a
> monospaced typeface, nor do I think they should be.  A proportional
> typeface generally looks better.
> 
> The price of that improved appearance is that the use of sequences of
> spaces to get columnar alignment breaks as soon as there is variation in
> the content.

I know.  And I tend to agree that proportional typeface is nicer for 
SYNOPSIS.

> 
> The traditional solution to this problem in the *roff language is to set
> tab stops.  However, man-pages(7) calls out tab stop manipulation as
> unportable man(7) usage.
> 
>         *  Example programs should be laid out according  to  Kernighan
>            and  Ritchie style, with 4‐space indents.  (Avoid the use of
>            TAB characters in source code!)
> 
> Now, section 2 and 3 synopses are not _example program_ source code, so
> a defense of tab usage could be made here, but a man page author simply
> trying to get their stuff documented could be forgiven for feeling that
> drawing such a distinction is hair-splitting.
> 
> Using spaces is, however, in my opinion, worse simply due to the effect
> on rendered output for everything that isn't a terminal.

I'm generally a tab user, so you won't find resistance from me to use 
them, especially if they improve the situation.

> 
> There are a few ways to address this issue.
> 
> A. Don't worry about it and let HTML/PostScript/PDF output look ugly.

I'd prefer to help them if I can.

> 
> B. Stick synopses, at least for section 2 and 3 man pages, in EX/EE
>     blocks [...].  My recollection is that Michael Kerrisk opposed this
>     practice.  I too don't think it's a great idea; the average glyph
>     width is lower in proportional fonts, so using it, you can fit more
>     content on an output line.

It would be an easy fix, if nothing else works nicely.  We can restrict 
it to type pages, where there is an objective reason to do that, and let 
function pages continue using proportinal typeface.

> 
> C. Use tabs anyway.  For results that will actually get what you want,
>     you will need to set the tab stops to ensure they're wide enough to
>     achieve the desired alignment.  The use of custom tab stops requires
>     invoking the `ta` request, and this is warned against in the
>     "Portability" section of groff_man(7) (to be part of
>     groff_man_style(7) in groff 1.23).  But by invoking the `nf` and `fi`
>     requests for other reasons, this project's pages have already crossed
>     that bridge.

That will be my first attempt.  But I won't try setting the width, since 
you've shown in the below explanations how brittle and difficult it is. 
  So, if the defaults work nicely (maybe using double tabs at some 
places), I'll use tabs.  Otherwise, I'm probably going to fallback to 
.EX/.EE.  What's your opinion on this?  Or do you prefer going directly 
to .EX/.EE for 3type/2type pages?

> 
> C1. Actually selecting values for the tab stops can be tedious.  You can
[...]
> 
> C2. Clever roff writers (sometimes too clever) reach for the \w escape
[...]
>      .ta \w'char*' \w'tm_gmtoff'
Not a nice thing.
[...]
> 
>      .TA char gmtoff
> 
>      This certainly looks much cleaner, and in fact it closely resembles
>      Texinfo's @multitable command.  But it is just a mask over the
>      `ta` request of frightening appearance above, not a silver bullet.

May be nice.

> 
> C3. The above has the problem that it relies upon the writer to know
>      which pieces of text between the tab stops are the longest.  This
>      sounds like an obvious thing that no one would ever screw up.
>      I think that assumption would be swiftly overturned.

Maybe you can set up .TA so that it takes the longest of a set of 
consecutive .TA?  That's already kind of tbl(1).  Maybe we should use 
tbl(1) for that :P.

Would you recommend me using tbl(1), or .EX, or tabs (in the simple way)?
[...]
> 
> D. Congratulations, you've discovered tbl(1).[1]

So it seems.

> 
> I guess my advice is to choose your poison.  I'll advise as best I can.
> 
I'll try a few things.


>> 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?
> 
> "Spacing around an em dash varies. Most newspapers insert a space before
> and after the dash, and many popular magazines do the same, but most
> books and journals omit spacing, closing whatever comes before and after
> the em dash right up next to it. This website prefers the latter, its
> style requiring the closely held em dash in running text."
> 
> https://www.merriam-webster.com/words-at-play/em-dash-en-dash-how-to-use
> 
> In the groff man pages, I too "close up" any space around em dashes, but
> I freely admit that this (1) doesn't look all that great in terminal
> rendering [it too closely resembles other dashes--a "fullwidth" dash
> taking two character cells would be preferable on purely esthetic
> grounds, and probably a nightmare to get terminal emulators to cope
> with] and (2) it frustrates my input style; since I don't want to use
> the `\c` escape sequence, I end up putting the words immediately outside
> the em-dashed aside on the "wrong" lines semantically.  Maybe I should
> just get over my allergy to `\c` now that I understand how it
> works.[citation needed]

So no single-sided space for em dashes --such as this one--, right? 
Maybe that's a construction of my brain, trying to make them a bit more 
logic...


Cheers,

Alex

> 
>> What is "&a."?  Is that documented somewhere?  I didn't know that
>> abbreviature.
> 
> Having seen наб's reply, it seems of a piece with "&c.", which was
> in English formerly (ca. 150 years ago) a common abbreviation for the
> Latin "et cetera".  Nowadays "etc." has fully supplanted "&c." while
> many native English speakers are shaky on what, exactly, it abbreviates,
> even spelling it "ect." because that better aligns with English language
> phonotactics.
> 
> I admit never having seen "&a." before in English writing.  Like
> Germans' use of "resp.", it may be a thing non-native speakers assume
> "ports" into English, but doesn't.
> 
> Regards,
> Branden
> 
> [1] https://git.savannah.gnu.org/cgit/groff.git/tree/src/preproc/tbl/tbl.1.man

-- 
Alejandro Colomar
Linux man-pages comaintainer; http://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

man(7) DS and DE macros (was: [PATCH 4/5] tm.3type: describe tm_zone, tm_gmtoff)

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 11145 bytes --]

[dropped наб from CC list; added groff@]

At 2022-07-22T12:57:53+0200, Alejandro Colomar (man-pages) wrote:
> You answered all that I thought you would, and even more.  As always,
> you surprise me with great knowledge that I didn't even know I could
> ask for, and that's the main reason I tend to not try to direct your
> answers.  They're always welcome (although sometimes the knowledge is
> too much for me, a novice groff(7) user, to understand it; but I try
> to).

Aww, shucks.  Well, never hesitate to correct or challenge me; the best
knowledge is tested knowledge.

> On 7/22/22 05:33, G. Branden Robinson wrote:
> > Oh, bother.  Bash autocompletion for "man" on my Debian bullseye is
> > too dumb to recognize this new man page suffix.  I trust someone
> > reading this is aware of the problem and is fixing it for the next
> > Debian release.  (Has someone filed this as a bug with the Debian
> > BTS?)
> 
> I don't think it's been reported.  I've detected some unpleasantness,
> but since I also had some unpleasantness with pages in the main
> sections, I didn't know if there was even more of it with subsections.
> 
> Was it trying to read a manual page from a relative path?

Yup.  I was "man -l"-ing inside my Git checkout of man-pages.

> That's where I find a lot of problems, and that's why I always `sudo
> make install` the pages, then read them from the system as usual.
> That makes it easier.  I improved the Makefile to make that loop
> experience something nice.
> 
> Anyway, would you mind reporting the bug you notice and CCing me?

If I work up the gumption to report it, I will CC you, yes.

> > Hmmm.  I'm attaching a screenshot of Okular's rendering of the
> > current state of tm(3type) in the Linux man-pages Git repository to
> > PostScript.
> 
> I only see a black 180 bytes image.  Probably not what you expected to
> send?

No indeed.  My Logitech thumb-operated trackball hates me, as does the
company--they don't even sell a corded version anymore.  Due to some
diabolical collusion with the alkaline cartel, their devices refuse to
operate reliably after a fresh battery has been installed for more than
about 71 seconds.

> Anyway, I used pdfman()[1] to read the page in PDF, and I get your
> point.

I'm trying the attachment again for the benefit of list readers.

> > Synopses in man pages, whether for section [168] commands or section
> > [23] C function calls or data types, are not typically set in a
> > monospaced typeface, nor do I think they should be.  A proportional
> > typeface generally looks better.
> > 
> > The price of that improved appearance is that the use of sequences
> > of spaces to get columnar alignment breaks as soon as there is
> > variation in the content.
> 
> I know.  And I tend to agree that proportional typeface is nicer for
> SYNOPSIS.

Yeah, I don't want to give that up.  Also I seem to remember that in the
Linux man-pages, some function declarations are already nearing or
exceeding the line limit.  Switching to Courier would make this happen
to more of them.

> I'm generally a tab user, so you won't find resistance from me to use
> them, especially if they improve the situation.

When I started to contributing to groff, I didn't think they had a place
in man pages outside of tbl(1) tables, but my resolve is softening.

> > There are a few ways to address this issue.
> > 
> > A. Don't worry about it and let HTML/PostScript/PDF output look ugly.
> 
> I'd prefer to help them if I can.
> 
> > B. Stick synopses, at least for section 2 and 3 man pages, in EX/EE
> >     blocks [...].  My recollection is that Michael Kerrisk opposed
> >     this practice.  I too don't think it's a great idea; the average
> >     glyph width is lower in proportional fonts, so using it, you can
> >     fit more content on an output line.
> 
> It would be an easy fix, if nothing else works nicely.  We can
> restrict it to type pages, where there is an objective reason to do
> that, and let function pages continue using proportinal typeface.

After a bit of pondering today, I had an idea--see below.

> > C. Use tabs anyway.  For results that will actually get what you
> >    want, you will need to set the tab stops to ensure they're wide
> >    enough to achieve the desired alignment.  The use of custom tab
> >    stops requires invoking the `ta` request, and this is warned
> >    against in the "Portability" section of groff_man(7) (to be part
> >    of groff_man_style(7) in groff 1.23).  But by invoking the `nf`
> >    and `fi` requests for other reasons, this project's pages have
> >    already crossed that bridge.
> 
> That will be my first attempt.  But I won't try setting the width,
> since you've shown in the below explanations how brittle and difficult
> it is.  So, if the defaults work nicely (maybe using double tabs at
> some places), I'll use tabs.  Otherwise, I'm probably going to
> fallback to .EX/.EE.  What's your opinion on this?  Or do you prefer
> going directly to .EX/.EE for 3type/2type pages?

I think going ahead and using tabs as a first cut is a good idea.  I
would recommend _against_ adding supplemental adjacent tabs to manually
correct cases of misalignment.  A tab character always causes motion to
the next tab stop to the right of the current drawing position, so it
should never happen that text overrunning a tab stop will get
overprinted.

Further, in groff, by default the number of tab stops is infinite,
spaced at half-inch (~1.3 cm) intervals.

[Imagined: a new man(7) macro that would use \w to compute the widths of
its arguments, add 1n, and set a tab stop for each.]
> >      .TA char gmtoff
> > 
> >      This certainly looks much cleaner, and in fact it closely
> >      resembles Texinfo's @multitable command.  But it is just a mask
> >      over the `ta` request of frightening appearance above, not a
> >      silver bullet.
> 
> May be nice.

I'm keeping the above content as preparation for the New Idea.

> > C3. The above has the problem that it relies upon the writer to know
> >      which pieces of text between the tab stops are the longest.
> >      This sounds like an obvious thing that no one would ever screw
> >      up.  I think that assumption would be swiftly overturned.
> 
> Maybe you can set up .TA so that it takes the longest of a set of
> consecutive .TA?  That's already kind of tbl(1).  Maybe we should use
> tbl(1) for that :P.

Yes, that seems a bridge too far to me.  If its features are needed,
there is no shame in reaching for tbl(1).

> Would you recommend me using tbl(1), or .EX, or tabs (in the simple
> way)?

Start with tabs.  If that proves unsatisfactory, consider my New Idea
below, or tbl(1).  Using EX/EE for some synopses but not others feels
ugly to me.

> > D. Congratulations, you've discovered tbl(1).[1]
> 
> So it seems.

I fancy that I reconstructed the sequence of events that led Mike Lesk
to write it.  This could of course be completely wrong.  ;-)

> So no single-sided space for em dashes --such as this one--, right?
> Maybe that's a construction of my brain, trying to make them a bit
> more logic...

I haven't seen that outside of things like more(1) prompts; my few
memories of such feel decades old, probably of bespoke implementations
for 1980s micros.

Or maybe I'm thinking of NetHack.[1]

So here's the crazy idea.

Check this out from groff's an-ext.tmac file.

259929625b (Werner LEMBERG      2007-01-15 07:17:24 +0000 267) .\" Start display.
259929625b (Werner LEMBERG      2007-01-15 07:17:24 +0000 268) .de DS
259929625b (Werner LEMBERG      2007-01-15 07:17:24 +0000 269) .  \" XXX to be written
259929625b (Werner LEMBERG      2007-01-15 07:17:24 +0000 270) ..
259929625b (Werner LEMBERG      2007-01-15 07:17:24 +0000 271) .
259929625b (Werner LEMBERG      2007-01-15 07:17:24 +0000 272) .
259929625b (Werner LEMBERG      2007-01-15 07:17:24 +0000 273) .\" End display.
259929625b (Werner LEMBERG      2007-01-15 07:17:24 +0000 274) .de DE
259929625b (Werner LEMBERG      2007-01-15 07:17:24 +0000 275) .  \" XXX to be written
259929625b (Werner LEMBERG      2007-01-15 07:17:24 +0000 276) ..

We've had these stub, empty definitions of display macros lying around
for over 15 years.

How about we put some life into them?

Your section 2 and 3 synopses don't use groff's SY/YS macros because
those fill the text and you don't want the text filled.  You also need
tab stops and command synopses never do.

Unfilled text is a common feature of display macros in *roff macro
packages (see groff_me(7), groff_mm(7), and groff_ms(7)).

So, we could define `DS` as an `nf` invocation and `DE` as `fi`.  This
would relieve the Linux man-pages from having to "reach down" and invoke
these requests directly.

But we can do better.

Historically, there isn't much demand in man pages for right-aligned
text or centering; means of encoding these requirements is a common
feature of "display start" macro arguments in other packages.

The macro definitions above ignore their arguments.  What if we made
`DS` accept a list of strings whose widths it would use to compute the
tab stops?  (If there are no arguments, it would do nothing with the tab
stops.)

That would make `DS` work like my straw-man `TA` above, and importantly,
would eliminate the need to un-deprecate `DT` to reset the tab stops.
The scope of your changed tab stops would end with `DE`.

Furthermore, noting the (elided from the email) concerns I had about
people rendering man pages at a different type size (as supported by the
`S` register) or the future potential to make the font family used for
the body text configurable, I think it would be valuable for this `DS`
macro to emit a warning if a tab stop thus computed exceeds the line
length.  Because this is done at formatting time, it is dynamic--it
takes into account the properties of the font being used for rendering.
So it can't be wrong, and will never be issued spuriously.[2]

This change would be less disruptive than `MR`.  `DS` and `DE` are
_already defined_, and have been in groff man(7) for 15+ years.  In the
short term you could keep the `nf` and `fi` requests within `DS` and
`DE` until groff 1.23 ages out of your support window.  groff 1.22.4 and
earlier won't render your pages any _worse_ than they are right now, but
groff 1.23 would handle them _better_.

It will be important to remember that this feature isn't as powerful as
tbl(1).  It will still rely on contributors updating the `DS` call to
contain the "longest" text appearing in each column.  This will
occasionally be overlooked and people will occasionally guess wrong.

Maybe it's not worth the trouble.

But maybe it is.  I think there is a chance that this feature would
capture as much table or tab stop functionality as most man pages
require.

Regards,
Branden

[1] https://github.com/NetHack/NetHack/blob/NetHack-3.7/doc/Guidebook.mn#L428
[2] famous last words

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

Re: man(7) DS and DE macros (was: [PATCH 4/5] tm.3type: describe tm_zone, tm_gmtoff)

[Alejandro Colomar]

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

Hi Branden,

On 7/23/22 00:20, G. Branden Robinson wrote:
> [dropped наб from CC list; added groff@]
> 
> At 2022-07-22T12:57:53+0200, Alejandro Colomar (man-pages) wrote:
>> You answered all that I thought you would, and even more.  As always,
>> you surprise me with great knowledge that I didn't even know I could
>> ask for, and that's the main reason I tend to not try to direct your
>> answers.  They're always welcome (although sometimes the knowledge is
>> too much for me, a novice groff(7) user, to understand it; but I try
>> to).
> 
> Aww, shucks.  Well, never hesitate to correct or challenge me; the best
> knowledge is tested knowledge.

:-}

Sure!

> 
>> On 7/22/22 05:33, G. Branden Robinson wrote:
>>> Oh, bother.  Bash autocompletion for "man" on my Debian bullseye is
>>> too dumb to recognize this new man page suffix.  I trust someone
>>> reading this is aware of the problem and is fixing it for the next
>>> Debian release.  (Has someone filed this as a bug with the Debian
>>> BTS?)
>>
>> I don't think it's been reported.  I've detected some unpleasantness,
>> but since I also had some unpleasantness with pages in the main
>> sections, I didn't know if there was even more of it with subsections.
>>
>> Was it trying to read a manual page from a relative path?
> 
> Yup.  I was "man -l"-ing inside my Git checkout of man-pages.

Since I don't see a big benefit in being able to normally read old 
releases of the manpages, I recommend you installing them into 
/usr/local.  If you even need to read an old man page, you can find it 
manually.

> No indeed.  My Logitech thumb-operated trackball hates me, as does the
> company--they don't even sell a corded version anymore.  Due to some
> diabolical collusion with the alkaline cartel, their devices refuse to
> operate reliably after a fresh battery has been installed for more than
> about 71 seconds.

Do you recommend those things?  I had contact with one when I was very 
little (like 10 yr old?) in a library, and have never seen one of those 
again.  I didn't like it at the time, but I might change my opinion now 
that I hate more and more the mouse every day.

> 
>> Anyway, I used pdfman()[1] to read the page in PDF, and I get your
>> point.
> 
> I'm trying the attachment again for the benefit of list readers.

I guess you forgot it, 'cause I can't see it :/.


> 
> I think going ahead and using tabs as a first cut is a good idea.  I
> would recommend _against_ adding supplemental adjacent tabs to manually
> correct cases of misalignment.  A tab character always causes motion to
> the next tab stop to the right of the current drawing position, so it
> should never happen that text overrunning a tab stop will get
> overprinted.

That's why I don't use (I did, but not anymore) tabs for alignment in C. 
  tabs for indentation, spaces for alignment.

Since we're doing alignment here, you're right, and I shouldn't use 
multiple tabs.  But I don't want to go so far as to configuring the tab 
width, not even with a macro.  That's too complex.

So in the end, I decided tbl(1) is the only sane way to do it (you don't 
need to think; at least not any more than the learning curve of tbl(1)). 
  When many pages use tbl(1) for the SYNOPSIS of types, even new 
contributors should find it easy to write a new structure following the 
examples.

>>> C3. The above has the problem that it relies upon the writer to know
>>>       which pieces of text between the tab stops are the longest.
>>>       This sounds like an obvious thing that no one would ever screw
>>>       up.  I think that assumption would be swiftly overturned.
>>
>> Maybe you can set up .TA so that it takes the longest of a set of
>> consecutive .TA?  That's already kind of tbl(1).  Maybe we should use
>> tbl(1) for that :P.
> 
> Yes, that seems a bridge too far to me.  If its features are needed,
> there is no shame in reaching for tbl(1).

I very much want those features (no need to think about which field will 
be the widest).  So, that leaves me with good ol' tbl(1).

> 
>> Would you recommend me using tbl(1), or .EX, or tabs (in the simple
>> way)?

We agree that we would like to avoid .EX.
tabs would be either imperfect, or too complicated, or we would be 
reinventing tbl(1), so let it be.
> 
>>> D. Congratulations, you've discovered tbl(1).[1]
>>
>> So it seems.

So it seems...

> 
> I fancy that I reconstructed the sequence of events that led Mike Lesk
> to write it.  This could of course be completely wrong.  ;-)

I guess, yes :D

> 
>> So no single-sided space for em dashes --such as this one--, right?
>> Maybe that's a construction of my brain, trying to make them a bit
>> more logic...
> 
> I haven't seen that outside of things like more(1) prompts; my few
> memories of such feel decades old, probably of bespoke implementations
> for 1980s micros.

I think books in Spanish tend to use single-spaced em dashes.  I'll try 
to remember to check when reading.

> 
> Or maybe I'm thinking of NetHack.[1]

Oh, yes, the other page in man6 :D

> 
> So here's the crazy idea.
> 

[...]

Sorry to completely drop it from the email, but I think it would be 
harder to use than tbl(1), for less functionality.  I'm already trying 
tbl(1).  Good news is I'll review your page!  I'll try to make it work 
without reading anything other than that page.

 > So it can't be wrong, and will never be issued spuriously.[2]


Cheers,

Alex

> 
> Regards,
> Branden
> 
> [1] https://github.com/NetHack/NetHack/blob/NetHack-3.7/doc/Guidebook.mn#L428
> [2] famous last words

Oh, that made me remember of someone that I know, that said the day of a 
release: "It must work, I tested it on my computer". LOL!

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

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