packages: Install development manpages in the -dev package

[ivy]

Summary

Add a new per-group SUBPACKAGE option to bsd.man.mk.  When MANSPLITPKG
is enabled, this is forced to "-man", otherwise it defaults to empty
but can be overridden by the caller.

Use this in bsd.lib.mk to install library manpages in the -dev package
instead of the base package.  This is nearly always preferable, since
library manpages are usually in section 2 or 3 and are only relevant
to people with development packages installed.

MFC after:      3 seconds

[emaste]

I think this is a good direction but dislike the repetition. Is there a way we can use variables based on e.g. .if ${__page:M*.[23]} to construct the appropriate INSTALL commands?

[ivy]

In D52832#1207167, @emaste wrote:

I think this is a good direction but dislike the repetition. Is there a way we can use variables based on e.g. .if ${__page:M*.[23]} to construct the appropriate INSTALL commands?

we could define ${${__group}INSTALL}.2 and .3, then use ${__page:E} to select the correct installer. this reduces the duplication but doesn't change the fundamental approach; in particular it means we'd also have to hardcode an installer for 3lua, which i just realised exists.

i'm wondering if we should take a different approach: add a MAN_DEV_PACKAGE option (exact spelling tbd) which Makefiles can set to explicitly put manpages in the -dev package. bsd.lib.mk could set this automatically to handle most libraries, and this also lets us fix devel manpages in section 1, like *-config commands.

[ivy]

do this a better way

instead of hardcoding handling for sections 2 and 3, add a new SUBPACKAGE
option to bsd.man.mk, as described in the commit message.

this gives us more flexibility in the future as to what manpages go in
which package.

[ivy]

add MAN*SUBPACKAGE options where needed

this is needed for a few Makefiles, mostly libraries that install manpages
in section 5 or 8. this is a bit more invasive than the original approach,
but the outcome is also better in terms of manpages going into the right
packages.

[olce]

It seems good indeed that not all man pages related to libraries go into separate packages, as some are targeted at administrators.

I'm wondering though if differing group names in each package (POSIX1E5, REGEX7, MAN57, etc.) is really useful. Also, repeating these names with the SUBPACKAGE suffix to set the variable to empty does not seem optimal, even if a minor inconvenience.

How about instead having lists of dev man pages (e.g., a unique MANDEV group) and another of "core" or admin ones (the existing MAN group, or something else) and set MANDEVSUBPACKAGE from a new MANDEV_SUBPACKAGE in bsd.man.mk? MAN_SUBPACKAGE would be set to empty by default, not -dev, and MANDEV_SUBPACKAGE is the one that would be set to -dev. As some further refinement, it might be convenient to just populate MANDEV from MAN, filtering on the sections, if MANDEV is not set from each individual Makefile.

share/mk/bsd.man.mk

110

Minor, but maybe add a test for a group called MAN_ here and accordingly trigger an error, to avoid footshooting (and if doing what I suggest in the main comment, for MANDEV_) as well.

[ivy]

In D52832#1210456, @olce wrote:

I'm wondering though if differing group names in each package (POSIX1E5, REGEX7, MAN57, etc.) is really useful.

in the case of libc, libc's Makefile includes all of these Makefiles, so i thought it was less confusing to have separate groups. i could just change these to use one MAN5 and MAN7 group for all the sub-Makefiles.

How about instead having lists of dev man pages (e.g., a unique MANDEV group) and another of "core" or admin ones (the existing MAN group, or something else)

this will require updating the manpage list for every library in the base system, which i'd like to avoid, and it's also more likely to cause regressions later since people will forget to do this...

As some further refinement, it might be convenient to just populate MANDEV from MAN, filtering on the sections, if MANDEV is not set from each individual Makefile.

... unless we do this as well, but i'd like to avoid adding more magic to the build system, at least when it comes to packages which is already quite magical.

also, a lot of section 5 or 7 manpages do belong in the -dev package; i only moved the ones which are clearly relevant to non-developers. i think putting section 5 and 7 in the base package by default will lead to at least as much extra logic moving the ones back to the -dev package which should be there.

share/mk/bsd.man.mk

110

how would you end up with a group called MAN_?

[ivy]

following discussion with olce, add a MANNODEV group

[olce]

lib/libutil/Makefile

35–36

Leftover from the previous version?

lib/libwrap/Makefile

15–16

Lost link?

share/mk/bsd.lib.mk

92

Groups must be fully spelled out, no?

93

IIUC, this introduces a subtle difference with respect to the previous version, which is that even if MK_MANSPLITPKG is not no, manual pages that shouldn't go into -dev still won't go into -man either. Was this intended?

If this was not intended, we could test for MK_MANSPLITPKG here or perhaps better (for independence of Makefiles) forcibly set ${__group}SUBPACKAGE to ${MAN_SUBPACKAGE} when initially empty in the .for __group in ${MANGROUPS} loop in bsd.man.mk.

share/mk/bsd.man.mk

110

Just someone doing a typo when modifying a Makefile, such as setting MAN_SUBPACKAGE instead of MANSUBPACKAGE. This does not always have consequences but could lead to some head-scratching moments. (To be clear, there is nothing wrong with the current code per se, that's just some foot-shooting prevention.)

[ivy]

review feedback

[ivy]

lib/libutil/Makefile

35–36

fixed

lib/libwrap/Makefile

15–16

fixed

share/mk/bsd.lib.mk

92

technically they don't need to start with MAN, but this was wrong since we refer it to that way in other places.

93

i think the cleanest solution is to test MK_MANSPLITPKG in bsd.man.mk, which i've done.

share/mk/bsd.man.mk

110

setting MAN_SUBPACKAGE won't create a new mangroup, you'd have to add it to MANGROUPS explicitly.

[ivy]

fix typo in bsd.man.mk

[olce]

share/man/man9/Makefile

3

Shouldn't we keep PACKAGE and instead add MANSUBPACKAGE, as done above for share/man/man3/makefile?

share/mk/bsd.man.mk

110

Right, I was confused.

[olce]

Seems good (disclaimer: I only did manual code analysis, but didn't test).

Please just pay attention to the new inline comment in share/man/man9/Makefile in case it might indicate another small problem.

[ivy]

share/man/man9/Makefile

3

this case is a little tricky because "kernel-man" is not a subpackage of "kernel", it's a standalone package called "kernel-man". setting MANPACKAGE here is required, iirc, to make sure we don't end up with a kernel-man-man package when MK_MANSPLITPKG is enabled (which forces MANSUBPACKAGE to -man).