Order priority issues for special 3type sub-section

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

I think this only affects timeval.3* and timespec.3*. 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.

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

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

Thanks,
Guillem

Hi Guillem!

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

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

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

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

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.

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

Have a lovely night!
Alex

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

They're super helpful for sure. It was really annoying to have to track down where some struct was documented if it wasn't in the page I had open right then. Now I can just do: man some_struct

- Oskari

Hi Oskari, Guillem,

Thanks!

BTW, it seems these APIs are not-so-recent to glibc:

$ git blame -- ./time/sys/time.h | grep -e TIMEVAL_TO_TIMESPEC -e TIMESPEC_TO_TIMEVAL
8be918b7bb2 (Ulrich Drepper     2001-01-28 00:00:08 +0000  38) # define TIMEVAL_TO_TIMESPEC(tv, ts) {                                   \
8be918b7bb2 (Ulrich Drepper     2001-01-28 00:00:08 +0000  42) # define TIMESPEC_TO_TIMEVAL(tv, ts) {                                   \

I'm preparing a manual page for them.

Have a loveyl night!
Alex

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

Hi Oskari,

I've found now why my MUAs don't include you in the reply. I've seen the following header in your message. I don't know if this is something you configured your MUA to send, or if it's an accident. Please have a look.

Mail-Followup-To: Alejandro Colomar <[email protected]>,
Guillem Jover <[email protected]>, [email protected]

Have a lovely night!
Alex

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

Quoth Alejandro Colomar:

The Mail-Followup-To header field is good and useful. And Mutt, for example, sends it by default, if you’re properly using lists and subscribe. “I’m subscribed to this list anyway, so you need not send followups to me separately as well.” More people should use and honor it.

/me unignores mail-followup-to

Hi Lennart,

Hmm, it's interesting. It messes with what's To and what's Cc, but it's better than just replying to the list, which I hate because you never know who's subscribed to it (e.g., most people in the groff@ mailing list don't send me a copy of their responses, and I'm not subscribed to the list; or in other lists, even if I'm subscribed to the list, I won't read most stuff unless either the subject looks interesting or I'm To or Cc).

While I'll keep not using it, I'll honor it, now I understand it. :)

Have a lovely day!
Alex

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

Hi!

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

Yeah, libbsd should not be providing man pages for system types.

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.

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

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

Hmmm, yeah, other languages live in other namespaces, so they do well using their own subsection.

But C libraries live in the same namespace as libc, so they do indeed implement the same interface (hopefully; I hate it when a library implements something different with the name of something already existing) in a different library.

This is the case of libbsd.

Though I understand other systems that you support have different rules, such as using 3m for libm stuff, so for supporting those systems, I understand you prefer to stay in 3bsd.

Good.

Have a lovely day!
Alex

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

Hi!

This has been done now as part of the libbsd 0.12.2 release.

Thanks,
Guillem

Hi Guillem!

Thanks! I saw it when checking the err.h link pages stuff. I thought of CCing you about the man-pages-6.7 release. :)

Have a lovely Spring!
Alex

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