Re: Regarding MESSAGEs during pkg_add installation of meta packages

[Greg Troxel <gdt%lexort.com@localhost>]

PHO <pho%cielonegro.org@localhost> writes:

> On 4/4/25 08:36, Greg Troxel wrote:
>
>>      Content that belongs in upstream documentation, e.g. because it is useful
>>      to someone building and using the software from upstream sources, should be
>>      submitted upstream. It may be placed in files/README.pkgsrc but should be
>>      marked as belonging upstream.
>
> There is one thing I'm unhappy with that. Having things in
> README.pkgsrc is definitely better than having nothing at all, but
> without a support from pkg_info, those files would be terribly hard to
> find. So I believe we should not delete MESSAGEs until we have some
> kind of infrastructure support.

I don't see it that way. It's normal to have to read man pages and
documentation to figure out how to do things.  We aren't going to create
a MESSAGE for every package that summarizes the man page.  We have had
for decades the convention that /usr/pkg/share/docs/foo/* has
non-man-page documentation for the foo package.  Making MESSAGE loud is
basically working around people not reading the documentation in the
standard place.  I don't see it as hard to find at all, and pkg_info -L
shows all docs and all man pages.

> One of the examples that come to my mind is sysutils/open-vm-tools,
> whose MESSAGE explains how to get it properly work on non-Linux
> platforms. In an ideal world where NetBSD is (at least) as popular as
> Linux, upstreams would surely make every effort to ensure their
> software run smoothly on NetBSD. But in reality, even if I submitted a
> NetBSD-specific usage guide (actually non-Linux-specific guide in this
> case) to the upstream, I cannot expect them to accept it or even keep
> it in their documentation in the future.

Your (rational) expecation that an upstream will be indifferent to
portability doesn't invalidate the idea that they should accept docs.

Under the proposed text, these explanations fit in README.pkgsrc (or
README.NetBSD if it's only about NetBSD) with a note that (part of it at
least) belongs upstream.

Under existing guidelines, MESSAGE content that is NetBSD specific is
not ok, as it's printed on all systems.

> Another example is audio/musicpd whose MESSAGE explains, again, how to
> get it work on NetBSD. The NetBSD in-kernel audio mixer, by default,
> does not allow multiple users to open the same audio device
> simultaneously. This is probably good for security but MPD really
> needs this restriction to be disabled. Upstream should document this,
> sure, but in reality it's not exactly reasonable to expect them to do
> that.

That's fine in README.NetBSD.  It has been out of bounds for MESSAGE for
years, as not leading to unrecoverable damage.  Or, it can be patched
into the man page or share/doc/mpd/README.md.  It is not that
execptional to have to adjust OS config to run various programs.