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:
OpenPGP_signature
Description: OpenPGP digital signature
