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

svn path=/head/; revision=54055

en_US.ISO8859-1/books/porters-handbook/pkg-files/chapter.xml

@@ -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,18 +140,10 @@
 	<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>
 
@@ -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>