Re: Order priority issues for special 3type sub-section

[Alejandro Colomar <alx@kernel.org>]

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

Hi Guillem!

On Thu, Mar 07, 2024 at 12:22:58AM +0100, Guillem Jover wrote:
> Hi!
> 
> I just realized the other day that we have currently a problem with
> the order priority for a couple of the manual pages in (at least) the
> 3type sub-section.

Yup, we do:

alx@debian:~$ man -wa timeval
/usr/share/man/man3/timeval.3bsd.gz
/usr/local/man/man3type/timeval.3type
/usr/share/man/man3/timeval.3type.gz
alx@debian:~$ man -w timeval
/usr/share/man/man3/timeval.3bsd.gz

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

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

> I think this only affects timeval.3* and timespec.3*.

I think so.

> 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;                           \
}


> 
> But perhaps this is a more general problem as «t» sorts pretty late,
> for example later than «3cxx», «3ncurses», «3perl», «3pm», «3p» or
> «3posix». And ah, now I recalled the SECTION option in man-db, which
> on my system already lists 3type before many others, but I guess the

Yeah, I remember talking to Colin Watson to have the new sections in the
right priority.

            1 n l 8 3 0 2 3type 3posix 3pm 3perl 3am 5 4 9 6 7

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

And in cases wher various projects offer the same page exact page, maybe
/etc/alternatives should decide.

> 
> (BTW, I very much like that these types are provided on their own
> manual pages, and their own sub-section, thanks for that!)

Thanks!!  I had to fight a bit for them.  It's good to read positive
feedback.  :)

> 
> Thanks,
> Guillem

Have a lovely night!
Alex

-- 
<https://www.alejandro-colomar.es/>
Looking for a remote C programming job at the moment.

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