Hi!
On Thu, 2024-03-07 at 01:42:14 +0100, Alejandro Colomar wrote:
> On Thu, Mar 07, 2024 at 12:22:58AM +0100, Guillem Jover wrote:
> > These pages have been provided by libbsd in the
> > 3bsd sub-section for some time, and that sorts earlier than 3type.
> > This has not been a problem for the section 3 pages, as then those
> > will always be preferred if present over the 3bsd ones. This also
> > means I might be reluctant to add new 3bsd manual pages related to
> > types, to avoid future occlusions.
>
> If you want to add a page for a type that glibc doesn't provide, feel
> free to do so. I even encourage you to use 3type, although that might
> be inconsistent with the rest of libbsd, so you may prefer to keep 3bsd.
I'd rather not stomp on any of the system section-space, also the
inconsistency and the behavior on other non-GNU or non-Linux systems.
But thanks for the offer. :)
> If you want to add a page for a type that is provided by glibc, just let
> me know, and I can provide the page instead. (Although it would be rare
> that you provide a page for a type that glibc provides.)
Yeah, libbsd should not be providing man pages for system types.
> > But I'm not
> > sure how best this would be solved though. :/ Hmm perhaps thinking
> > about it, I could rewrite these manual pages and only provide them
> > for the TIMEVAL_TO_TIMESPEC and TIMESPEC_TO_TIMEVAL macros.
>
> Actually, glibc provides these macros, so I should probably write pages
> for those too. Maybe I can write something and then just drop the
> libbsd pages. BTW, why do you provide those macros if glibc also
> provides them? Maybe they are recent additions to glibc?
>
>
> alx@debian:~/src/gnu/glibc/master$ grepc TIMEVAL_TO_TIMESPEC .
> ./time/sys/time.h:# define TIMEVAL_TO_TIMESPEC(tv, ts) { \
> (ts)->tv_sec = (tv)->tv_sec; \
> (ts)->tv_nsec = (tv)->tv_usec * 1000; \
> }
> alx@debian:~/src/gnu/glibc/master$ grepc TIMESPEC_TO_TIMEVAL .
> ./time/sys/time.h:# define TIMESPEC_TO_TIMEVAL(tv, ts) { \
> (tv)->tv_sec = (ts)->tv_sec; \
> (tv)->tv_usec = (ts)->tv_nsec / 1000; \
> }
Ah, thanks, didn't check, and assumed these were not present. Digging
a bit now it seems these came included as part of the fix for:
https://bugs.freedesktop.org/show_bug.cgi?id=94320
which was for non-glibc systems! And I guess I included the man page
for completeness and there was no support for selection per system
yet.
> > problem is still that unlisted sub-sections get folded into their
> > parent section, so perhaps some of these need to be proposed for
> > addition there. Not sure about other man pagers though.
>
> I think projects shouldn't use their own subsection. They should
> instead use the same sections, in this case 3type, and use LIBRARY to
> document the library needed to get the thing.
I don't think this works as a general rule, because different projects
might want to document things that live in different namespaces. For
things that are going to be "enforced" to share the same namespace
such as programs, or header files, then that's fine. But for function
interfaces or language features, for example which might be the same
on different implementations using sub-section makes sense to me. For
example it seems it would be rather inappropriate to document perl's
if(3perl) as if(3). :)
> And in cases wher various projects offer the same page exact page, maybe
> /etc/alternatives should decide.
alternatives are supposed to be used for the same interface, not for
conflicting and unrelated ones, in this case if these document stuff
that is completely different then that would not seem appropriate.
In this particular case, what I'll be doing is to remove the
timeval(3bsd), timespec(3bsd) links everywhere, and stop installing
the TIMEVAL_TO_TIMESPEC(3bsd) and TIMESPEC_TO_TIMEVAL(3bsd) on glibc
based systems, and check on what others these are already provided,
and install those there conditionally.
Thanks,
Guillem
