svn commit: r51913 - in head/en_US.ISO8859-1/books/porters-handbook: pkg-files plist special

[Mathieu Arnold]

Author: mat
Date: Wed Jun 27 13:58:42 2018
New Revision: 51913
URL: https://svnweb.freebsd.org/changeset/doc/51913

Log:
  Add notes in various places about the policy to not start or stop services.
  
  Sponsored by:	Absolight
  Differential Revision:	https://reviews.freebsd.org/D16034

Modified:
  head/en_US.ISO8859-1/books/porters-handbook/pkg-files/chapter.xml
  head/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml
  head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml

Modified: head/en_US.ISO8859-1/books/porters-handbook/pkg-files/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/pkg-files/chapter.xml	Tue Jun 26 14:48:48 2018	(r51912)
+++ head/en_US.ISO8859-1/books/porters-handbook/pkg-files/chapter.xml	Wed Jun 27 13:58:42 2018	(r51913)
@@ -63,6 +63,14 @@
       mode the script is being run in.  The <envar>PKG_PREFIX</envar>
       environmental variable will be set to the package installation
       directory.</para>
+
+    <important>
+      <para>This script is here to help you set up the package so that
+	it is as ready to use as possible.  It <emphasis>must
+	  not</emphasis> be abused to start services, stop services,
+	or any other commands that will modify the currenly running
+	system.</para>
+    </important>
   </sect1>
 
   <sect1 xml:id="pkg-deinstall">
@@ -80,6 +88,14 @@
       mode the script is being run in.  The <envar>PKG_PREFIX</envar>
       environmental variable will be set to the package installation
       directory</para>
+
+    <important>
+      <para>This script is here to help you set up the package so that
+	it is as ready to use as possible.  It <emphasis>must
+	  not</emphasis> be abused to start services, stop services,
+	or any other commands that will modify the currenly running
+	system.</para>
+    </important>
   </sect1>
 
   <sect1 xml:id="pkg-names">

Modified: head/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml	Tue Jun 26 14:48:48 2018	(r51912)
+++ head/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml	Wed Jun 27 13:58:42 2018	(r51913)
@@ -661,6 +661,14 @@ PLIST_SUB=	PERL_ARCH=mach</programlisting>
 	    </listitem>
 	  </varlistentry>
 	</variablelist>
+
+	<important>
+	  <para>These keywords are here to help you set up the package
+	    so that it is as ready to use as possible.  They
+	    <emphasis>must not</emphasis> be abused to start services,
+	    stop services, or any other commands that will modify the
+	    currenly running system.</para>
+	</important>
       </sect3>
 
       <sect3 xml:id="plist-keywords-base-mode">

Modified: head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml	Tue Jun 26 14:48:48 2018	(r51912)
+++ head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml	Wed Jun 27 13:58:42 2018	(r51913)
@@ -5561,6 +5561,15 @@ run_rc_command "$1"</programlisting>
       <literal>_enable</literal> variable is not optional,
       and must use the ":" for the default.</para>
 
+    <important>
+      <para>Ports <emphasis>must not</emphasis> start and stop
+	themselves when installing and deinstalling.  Do not abuse the
+	<filename>plist</filename> keywords described in <xref
+	  linkend="plist-keywords-base-exec"/> to run commands
+	starting services, stopping services, or any other commands
+	that will modify the currenly running system.</para>
+    </important>
+
     <sect2 xml:id="rc-scripts-checklist">
       <title>Pre-Commit Checklist</title>