svn commit: r54055 - head/en_US.ISO8859-1/books/porters-handbook/pkg-files

Author: mat
Date: Tue Apr 14 14:27:54 2020
New Revision: 54055
URL: https://svnweb.freebsd.org/changeset/doc/54055

Log:
  Fix the pkg-message documentation, it ways lagging behind policies.

Modified:
  head/en_US.ISO8859-1/books/porters-handbook/pkg-files/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	Mon Apr 13 14:53:20 2020	(r54054)
+++ head/en_US.ISO8859-1/books/porters-handbook/pkg-files/chapter.xml	Tue Apr 14 14:27:54 2020	(r54055)
@@ -62,8 +62,8 @@
 	<term>raw</term>
 
 	<listitem>
-	  <para>A regular plain text file.  Its message is always
-	    displayed, on install, and on upgrade.</para>
+	  <para>A regular plain text file.  Its message is only
+	    displayed on install.</para>
 	</listitem>
       </varlistentry>
 
@@ -140,19 +140,11 @@
 	<literal>minimum_version</literal> keywords can be
 	combined.</para>
 
-      <para>The <literal>type</literal> keyword can have four
+      <para>The <literal>type</literal> keyword can have three
 	values:</para>
 
       <variablelist>
 	<varlistentry>
-	  <term>(no type specified)</term>
-
-	  <listitem>
-	    <para>The message is always displayed.</para>
-	  </listitem>
-	</varlistentry>
-
-	<varlistentry>
 	  <term><literal>install</literal></term>
 
 	  <listitem>
@@ -199,7 +191,7 @@
 	  strings:</para>
 
 	<programlisting>[
-{
+{ type: install
   message: "Simple message"
 }
 ]</programlisting>
@@ -219,7 +211,7 @@
 	  as:</para>
 
 	<programlisting>[
-{
+{ type: install
   message: &lt;&lt;EOM
 Simple message
 EOM
@@ -227,31 +219,6 @@ EOM
 ]</programlisting>
       </example>
 
-      <example xml:id="porting-message-ucl-ex1">
-	<title>Always Display a Message</title>
-
-	<para>If a port has a <filename>pkg-message</filename>
-	  containing simple text, it can be transformed into
-	  <acronym>UCL</acronym> easily.  Given this
-	  <filename>pkg-message</filename>:</para>
-
-	<programlisting>*   BIND requires configuration of rndc, including a "secret" key.   *
-*    The easiest, and most secure way to configure rndc is to run    *
-*   'rndc-confgen -a' to generate the proper conf file, with a new   *
-*            random key, and appropriate file permissions.           *</programlisting>
-
-	<programlisting>[
-{
-  message: &lt;&lt;EOD
-*   BIND requires configuration of rndc, including a "secret" key.   *
-*    The easiest, and most secure way to configure rndc is to run    *
-*   'rndc-confgen -a' to generate the proper conf file, with a new   *
-*            random key, and appropriate file permissions.           *
-EOD
-}
-]</programlisting>
-      </example>
-
       <example xml:id="porting-message-ucl-ex2">
 	<title>Display a Message on Install/Deinstall</title>
 
@@ -295,6 +262,14 @@ EOD
   message: "Upgrading from &gt; 1.0 and &lt; 3.0 remove that file."
 }
 ]</programlisting>
+
+	<important>
+	  <para>When displaying a message on upgrade, it is important
+	    to limit when it is being shown to the user.  Most of the
+	    time it is by using <literal>maximum_version</literal> to
+	    limit its usage to upgrades from before a certain version
+	    when something specific needs to be done.</para>
+	</important>
       </example>
     </sect2>
   </sect1>
_______________________________________________
[email protected] mailing list
https://lists.freebsd.org/mailman/listinfo/svn-doc-all
To unsubscribe, send any mail to "[email protected]"