Order priority issues for special 3type sub-section

Order priority issues for special 3type sub-section

[Guillem Jover]

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

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

[Alejandro Colomar]

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

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

[Oskari Pirhonen]

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

On Thu, Mar 07, 2024 at 01:42:14 +0100, Alejandro Colomar wrote:
> Hi Guillem!
> 
> On Thu, Mar 07, 2024 at 12:22:58AM +0100, Guillem Jover wrote:
> > 
> > (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.  :)
> 

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

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

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

[Alejandro Colomar]

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

Hi Oskari, Guillem,

On Wed, Mar 06, 2024 at 07:08:20PM -0600, Oskari Pirhonen wrote:
> 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

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.

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

Mail-Followup-To header (was: Order priority issues for special 3type sub-section)

[Alejandro Colomar]

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

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 <alx@kernel.org>,
        Guillem Jover <guillem@hadrons.org>, linux-man@vger.kernel.org

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

Re: Mail-Followup-To header (was: Order priority issues for special 3type sub-section)

[Lennart Jablonka]

Quoth Alejandro Colomar:
>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 <alx@kernel.org>,
>        Guillem Jover <guillem@hadrons.org>, linux-man@vger.kernel.org

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

Re: Mail-Followup-To header (was: Order priority issues for special 3type sub-section)

[Alejandro Colomar]

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

Hi Lennart,

On Thu, Mar 07, 2024 at 09:37:43AM +0000, Lennart Jablonka wrote:
> Quoth Alejandro Colomar:
> > 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 <alx@kernel.org>,
> >        Guillem Jover <guillem@hadrons.org>, linux-man@vger.kernel.org
> 
> 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.”

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

> More people should use and honor it.

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

> /me unignores mail-followup-to

Have a lovely day!
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 --]

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

[Guillem Jover]

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

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

[Alejandro Colomar]

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

On Thu, Mar 07, 2024 at 05:06:29AM +0100, Guillem Jover wrote:
> > 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). :)

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

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

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.

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

Good.

Have a lovely day!
Alex

> 
> Thanks,
> Guillem

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

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

[Guillem Jover]

Hi!

On Thu, 2024-03-07 at 05:06:29 +0100, Guillem Jover wrote:
> 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.

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

Thanks,
Guillem

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

[Alejandro Colomar]

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

On Wed, Mar 20, 2024 at 10:18:31AM +0100, Guillem Jover wrote:
> Hi!

Hi Guillem!

> On Thu, 2024-03-07 at 05:06:29 +0100, Guillem Jover wrote:
> > 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.
> 
> This has been done now as part of the libbsd 0.12.2 release.

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

> Thanks,
> Guillem

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