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

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

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