CVS commit: pkgsrc/doc/guide/files

["Greg Troxel" <gdt%netbsd.org@localhost>]

Module Name:    pkgsrc
Committed By:   gdt
Date:           Fri Mar 26 17:43:20 UTC 2021

Modified Files:
        pkgsrc/doc/guide/files: components.xml

Log Message:
guide: Modernize MESSAGE section

Based on tech-pkg traffic over the last few years that appears to have
rough consensus, adjust MESSAGE section to explain that it should only
be used for exceptional circumstances, and specifically not to
substitute for documentation that belongs in the package's docdir.


To generate a diff of this commit:
cvs rdiff -u -r1.59 -r1.60 pkgsrc/doc/guide/files/components.xml

Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.

Modified files:

Index: pkgsrc/doc/guide/files/components.xml
diff -u pkgsrc/doc/guide/files/components.xml:1.59 pkgsrc/doc/guide/files/components.xml:1.60
--- pkgsrc/doc/guide/files/components.xml:1.59  Sun May 17 00:54:00 2020
+++ pkgsrc/doc/guide/files/components.xml       Fri Mar 26 17:43:20 2021
@@ -1,4 +1,4 @@
-<!-- $NetBSD: components.xml,v 1.59 2020/05/17 00:54:00 tnn Exp $ -->
+<!-- $NetBSD: components.xml,v 1.60 2021/03/26 17:43:20 gdt Exp $ -->
 
 <chapter id="components"> <?dbhtml filename="components.html"?>
 <title>Package components - files, directories and contents</title>
@@ -572,10 +572,30 @@ FILES_SUBST+=  SOMEVAR="somevalue"
 
          <listitem>
            <para>This file is displayed after installation of the package.
-           Useful for things like legal notices on almost-free
-           software and hints for updating config files after
-           installing modules for apache, PHP etc.
-           Please note that you can modify variables in it easily by using
+           While this was used often in the past, it has two
+           problems: the display will be missed if many packages are
+           intalled 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.</para>
+           <para>MESSAGE should not be used for:</para>
+           <itemizedlist>
+             <listitem><para>exhortations to read the documentation</para></listitem>
+             <listitem><para>reminders to install rc.d files and set variables</para></listitem>
+             <listitem><para>anything that should be explained in the
+             installation/configuration documentation that should
+             come with the package</para></listitem>
+           </itemizedlist>
+           <para>If the documentation provided by upstream needs
+           enhancing, create e.g. files/README.pkgsrc and install it
+           in the package's documentation directory.
+           </para>
+           <para>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.</para>
+           <para>Note that you can modify variables in it easily by using
            <varname>MESSAGE_SUBST</varname> in the package's
            <filename>Makefile</filename>:</para>