In D51089#1166071, @mandree wrote:

Thanks for the contribution, but I think this arrives too early (unless I've missed documentation, and I believe I checked the usual places).

I don't understand this.

In particular, I reject the word "abuse" in the context of making manual page installation conditional on DOCS - what do you base this assessment on?

Looking at the ports tree only a few < 20 ports install manpages with docs, everyone else uses either MANPAGES or nothing. This is just a consistency cleanup. I am not attached to the word 'abuse' and don't want to go into political discussions. If you feel better I can change it to whatever you like.

I understand some people may want to split MANPAGES out of DOCS, but I do not yet see any reasoning why we need to do that.
We've had many years where NOPORTDOCS, or undefining the DOCS option, also avoided manual pages (which usually serves the purpose on machines not used interactively), and how would established practice be "abuse"?

MANPAGES as knob also is not documented at all, unlike DOCS. I don't consider this an official knob yet. More or less the only reference is this line shown below, which is a common help line if and only if MANPAGES is in a port's OPTIONS_DEFINE list. I cannot find anything in the online porter's handbook or CHANGES or UPDATING or Mk/bsd.port.mk. I think this deserves a formal discussion on whether we want to pursue this, and if we decide that way, we need docs in place first.

/usr/ports/Mk/bsd.options.desc.mk
328:MANPAGES_DESC?=             Build and/or install manual pages

Splitting does make sense if you look what amount of stuff DOCS installs compared to MANPAGES. One example is lang/rust. DOCS are abysmal. Also for those who deploy on servers they usually want to retain manpages, don't access documentation mostly through a browser. There are likely other usecases.

If you think that MANPAGES should be official, though the description has been there for a long time, feel free to raise a discussion on the approriate mailing list.

I just spotted those ports by coincidence and decided that their options behavior should be consistent with those which use MANPAGES for manpages.

Comparison:

osipovmi@deblndw011x:~/var/Projekte/freebsd/ports (main =)
$ grep -r --include='*pkg-plist*' /man/  . | grep -v MANPAGES | cut -f 1 -d :  | sort -u | wc -l
    3970
osipovmi@deblndw011x:~/var/Projekte/freebsd/ports (main =)
$ grep -r --include='*pkg-plist*' /man/  . | grep  MANPAGES | cut -f 1 -d :  | sort -u | wc -l
     136
osipovmi@deblndw011x:~/var/Projekte/freebsd/ports (main =)
$ grep -r --include='*pkg-plist*' /man/  . | grep -v MANPAGES | grep -v DOCS |  cut -f 1 -d :  | sort -u | wc -l
    3910

This means that we either should use MANPAGES consistently or remove it straight away.

@mandree, how to proceed here?

In D51089#1171296, @michaelo wrote:

@mandree, how to proceed here?

Get things around MANPAGES formally documented first. CHANGES, Mk/bsd.port.mk or thereabouts, and the porter's handbook, or show me where all these documentation is to be found.
We can't sustain using features that aren't documented and just "everybody just does it".

MANPAGES is a new invention and we used to use DOCS. I understand the motivation to split things up and leave out documentation (which is a non-issue for openexr because the documentation is in a separate port in order to solve a circular dependency), but if we don't document this properly in the porter's handbook and CHANGES, then we'll sooner or later run into inconsistencies. We've been there before.

And I'm not the proponent of switching my port to some undocumented feature of the ports tree, so I'm also not the one making the proposals and getting the decisions.