Re: Regarding MESSAGEs during pkg_add installation of meta packages

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

Solvable Hat <notsolvablehat%gmail.com@localhost> writes:

> After searching for a bit, I found MESSAGEs during the installation of
> gnome (pkg_add gnome-3.38.1nb1). I hope the messages within "===" are
> MESSAGEs.
> I have attached the output file.
> And yeah, I looked into /usr/pkgsrc and found many
> MESSAGES/INSTALL/DEINSTALL.

You did find them, but almost all of the uses of MESSAGE are outside of
policy and should be removed.

> Greg, you are suggesting that instead of MESSAGEs during installation,
> updation and deletion, a global readme package like README.pkgsrc be
> printed at the end of the installation of packages?

No, I am saying that the practice of putting information in MESSAGE is
wrong, when that information is telling the user to read documentation,
or information that belongs in documentation.  This is the group's
agreed opinion, recorded by me after proposing the text and receiving no
objections.

The key point is:

  It should therefore be used only in exceptional circumstances where
  lasting negative consequences would result from someone not reading
  it.

and the full text is:

  MESSAGE

      This file is displayed after installation of the package. While this was
      used often in the past, it has two problems: the display will be missed if
      many packages are installed at once, and the person installing the package
      and the one using or configuring it may be different. It should therefore
      be used only in exceptional circumstances where lasting negative
      consequences would result from someone not reading it.

      MESSAGE should not be used for:

        + exhortations to read the documentation

        + reminders to install rc.d files and set variables

        + anything that should be explained in the installation/configuration
          documentation that should come with the package

      If the documentation provided by upstream needs enhancing, create e.g.
      files/README.pkgsrc and install it in the package's documentation
      directory.

      Note that MESSAGE is shown for all operating systems and all init systems.
      If a MESSAGE is necessary, it should be narrowed to only those operating
      systems and init systems to which it applies.

      Note that you can modify variables in it easily by using MESSAGE_SUBST in
      the package's Makefile:

      MESSAGE_SUBST+=  SOMEVAR="somevalue"

      replaces "${SOMEVAR}" with "somevalue" in MESSAGE. By default, substitution
      is performed for PKGNAME, PKGBASE, PREFIX, LOCALBASE, X11BASE,
      PKG_SYSCONFDIR, ROOT_GROUP, and ROOT_USER.

      You can display a different or additional files by setting the MESSAGE_SRC
      variable. Its default is MESSAGE, if the file exists.


When someone wants to use MESSAGE for a purpose other than telling the
user to read the documentation, it's usually because there should be
something documented that shouldn't.  When it belongs upstream in the
admin guide, install guide, etc., then that should be filed upstream as
a bug.  When it is pkgsrc specific for the foo package, it should be put
in a files/README.pkgsrc in the package which is then installed into
$prefix/share/doc/foo/README.pkgsrc, where it is available when the user
looks for documentation.

>> `> In other words - also if we won't have any MESSAGEs - we probably still
>> have such UI/UX problems when installing/updating/deleting a lot of
>> packages at the same time.
> `
> I did not understand this part.
>
> Please tell me that I am going in the right direction.

For example, the dbus MESSAGE talking about rc.d is wrong.  Many
packages have rc.d scripts and this is not notable at the shouting
level, and it's explicitly noted as inappropriate in the guide.  People
who want them installed automatically should set RCD_SCRIPTS=yes, and
people who don't need to pay attention to which ones they want
installed.  Just because a package has a script doesn't mean that the
uesr will choose to run it.

Similarly, for Xwayland-session, if the upstream program needs a config
file (that's buggy too), then the package should use CONF_FILES.  But in
any case, "program needs configuring" is not unusual, and the user
should be consulting the upstream docs for things they intend to run.

So I don't think that making a situation where there are excessive
MESSAGE files prettier is a good thing, because it aligns with an
expectation that we aren't going to fix what's wrong.

However, there are a few legitimate uses, and there may be legitimate
output from INSTALL/DEINSTALL.

I think you're talking about batching hem during pkg_add, but it's
equally important that this happen with pkgin.

I wonder if your motivation to work on this is personally finding it
confusing, or something else.  It seems like a fairly small effort to
adjust pkg_add, and a bit more to think about pkgin.