Re: [IDEA] New pages for types: structs and typedfefs

[Guillem Jover <guillem@hadrons.org>]

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@gmail.com> 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