Hi! [ I see this has already been merged, just giving some little context, from the libbsd side. :) ] On Sun, 2020-09-13 at 14:01:22 +0200, Michael Kerrisk (man-pages) wrote: > On Sat, 12 Sep 2020 at 10:59, Alejandro Colomar <colomar.6.4.3@xxxxxxxxx> wrote: > > On 2020-09-12 08:33, Michael Kerrisk (man-pages) wrote: > > > Your not the first to suggest this. Most recently, if I recall > > > correctly, Florian also suggested it. > > > > > > The idea seems reasonable, but I wonder about the best way of doing it. Yes, this sounds great, this is also something I've missed from time to time. :) > > libbsd already provides a few pages on types. Maybe we could have a > > look at them. At least I've seen 'man timespec' (which redirects to > > timeval.3bsd): > > > > https://gitlab.freedesktop.org/libbsd/libbsd/-/blob/master/man/timeval.3bsd Ah, timespec.3bsd is actually (at least) a man-db construct, libbsd does not install an actual link on disk, I assume the .Nm macros in the .Sh NAME section are being indexed. I should add such explicit link for completeness though, thanks! > > > Then of course, we'd need to have links to that page, so that > > > people could just type 'man timer_t'. What section should the links > > > be in? The reasonable candidates would be section 3 or 7. I'm not > > > yet sure which is better. But the point is that we'd have files > > > such as timer_t.3 (or timer_t.7) that are link pages containing the > > > line: > > > > > > .so man7/system_data_types.7 > > > > Sure. And for the structs, I'd allow: > > > > 'man struct timespec' (For simplicity) > > 'man struct-timespec' (Similar to the git man pages) > > 'man timespec' (For compatibility with libbsd) > > Mainly, I'm interested in the last case. That's the one I think that > people would most likely use. In a follow-up mail, you expressed > concern with conflicts with libbsd pages. I'm not too worried about > that. There are already *many* conflicts between libbsd and man-pages. In libbsd I try to have man pages for at least every function and macro, ideally originating from the related BSD. The timeval.3bsd came mostly out of a need to document the TIMEVAL_TO_TIMESPEC and TIMESPEC_TO_TIMEVAL macros, and finding this on NetBSD: <http://man.netbsd.org/timeval.3> and they do seem to have dedicated man pages for some other structures, which seems rather nice, and indeed worth imitating. Regarding conflicts, I specifically chose to place all libbsd man pages in the 3bsd section (both in filename and in the .Dt macro, to avoid an actual conflict, and to not override the system man pages. So once a man page appears in say man-pages, then that will take precedence: $ man explicit_bzero # man-pages version recentish addition vs $ man 3bsd explicit_bzero # libbsd version Thanks, Guillem
