Clarify the use of the "shutdown" rcorder(8) keyword.

Requested by:	rafan
Ideas by:	dougb

en_US.ISO8859-1/articles/rc-scripting/article.sgml

@@ -1096,8 +1096,21 @@ run_rc_command "$1"</programlisting>
       </callout>
 
       <callout arearefs="rcng-hookup-keyword">
-	<para><anchor id="keywords">There are several keywords used
+	<para><anchor id="keywords">As we remember from the above text,
-	  in &os;:</para>
+	  &man.rcorder.8; keywords can be used to select or leave
+	  out some scripts.  Namely any &man.rcorder.8; consumer
+	  can specify through <option>-k</option> and <option>-s</option>
+	  options which keywords are on the <quote>keep list</quote> and
+	  <quote>skip list</quote>, respectively.  From all the
+	  files to be dependency sorted, &man.rcorder.8; will pick
+	  only those having a keyword from the keep list (unless empty)
+	  and not having a keyword from the skip list.</para>
+
+	<para>In &os;, &man.rcorder.8; is used by
+	  <filename>/etc/rc</filename> and
+	  <filename>/etc/rc.shutdown</filename>.  These two scripts
+	  define the standard list of &os; <filename>rc.d</filename>
+	  keywords and their meanings as follows:</para>
 
 	<variablelist>
 	  <varlistentry>
@@ -1127,10 +1140,33 @@ run_rc_command "$1"</programlisting>
 	    <term><literal>shutdown</literal></term>
 
 	    <listitem>
-	      <para>The script wants to be run during system
+	      <para>The script wants to run during system shutdown.
-		shutdown.  Without the keyword listed,
+
-		<filename>/etc/rc.shutdown</filename> would ignore
+	      <note>
-		it for faster shutdown.</para>
+		<para>When the system is shut down,
+		  <filename>/etc/rc.shutdown</filename> runs.  It
+		  assumes that most <filename>rc.d</filename> scripts
+		  have nothing to do at system shutdown time.  For
+		  faster shutdown, <filename>/etc/rc.shutdown</filename>
+		  selectively invokes scripts with the
+		  <literal>shutdown</literal> keyword and passes
+		  the <option>faststop</option> command to them.</para>
+
+		<para>Threrefore, when writing a real
+		  <filename>rc.d</filename> script, you should
+		  consider whether it is relevant at system shutdown
+		  time.  E.g., if your script does its work in
+		  response to the <option>start</option> command
+		  only, then you need not include this keyword.
+		  However, if your script manages a service, it is
+		  probably a good idea to stop it before the system
+		  proceeds to the final stage of its shutdown
+		  sequence descriped in &man.halt.8;.  In particular,
+		  a service should be stopped explicitly if it needs
+		  considerable time or special actions to shut down
+		  cleanly.  A typical example of such a service is
+		  a database engine.</para>
+	      </note>
 	    </listitem>
 	  </varlistentry>
 	</variablelist>