docs/172692: [PATCH] Bring parts of the rc scripting guides up to date

[Chris Rees]

>Number:         172692
>Category:       docs
>Synopsis:       [PATCH] Bring parts of the rc scripting guides up to date
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          change-request
>Submitter-Id:   current-users
>Arrival-Date:   Sun Oct 14 13:10:00 UTC 2012
>Closed-Date:
>Last-Modified:
>Originator:     Chris Rees
>Release:        FreeBSD 9.0-RELEASE amd64
>Organization:
>Environment:
System: FreeBSD pegasus.bayofrum.net 9.0-RELEASE FreeBSD 9.0-RELEASE #0: Sun Apr 29 12:29:02 BST 2012 root at pegasus.bayofrum.net:/usr/obj/usr/src/sys/PEGASUS amd64


        
>Description:
        The RC scripting guide is a little out of date, since it doesn't match current practice.  Also, tighten up on some terminology.
>How-To-Repeat:
	
>Fix:

	

--- rc-scripting-modernise.diff begins here ---
Index: article.xml
===================================================================
--- article.xml	(revision 39747)
+++ article.xml	(working copy)
@@ -400,8 +400,8 @@
 stop_cmd=":"
 
 load_rc_config $name<co id="rcng-confdummy-loadconfig"/>
-eval "${rcvar}=\${${rcvar}:-'NO'}"<co id="rcng-confdummy-enable"/>
-dummy_msg=${dummy_msg:-"Nothing started."}<co id="rcng-confdummy-opt"/>
+: ${dummy_enable:=no} <co id="rcng-confdummy-enable"/>
+: ${dummy_msg="Nothing started."}<co id="rcng-confdummy-opt"/>
 
 dummy_start()
 {
@@ -448,7 +448,7 @@
 	  system, you should add a default setting for the knob to
 	  <filename>/etc/defaults/rc.conf</filename> and document
 	  it in &man.rc.conf.5;.  Otherwise it is your script that
-	  should provide a default setting for the knob.  A portable
+	  should provide a default setting for the knob.  The canonical
 	  approach to the latter case is shown in the example.</para>
 
 	<note>
@@ -479,7 +479,7 @@
 	<important>
 	  <para>The names of all &man.rc.conf.5; variables used
 	    exclusively by our script <emphasis>must</emphasis>
-	    have the same prefix: <envar>${name}</envar>.  For
+	    have the same prefix: <envar>${name}_</envar>.  For
 	    example: <envar>dummy_mode</envar>,
 	    <envar>dummy_state_file</envar>, and so on.</para>
 	</important>
@@ -491,15 +491,6 @@
 	    our script will save us from possible
 	    collisions with the &man.rc.subr.8; namespace.</para>
 
-	  <para>As long as an &man.rc.conf.5; variable and its
-	    internal equivalent are the same, we can use a more
-	    compact expression to set the default value:</para>
-
-	  <programlisting>: ${dummy_msg:="Nothing started."}</programlisting>
-
-	  <para>The current style is to use the more verbose form
-	    though.</para>
-
 	  <para>As a rule, <filename>rc.d</filename> scripts of the
 	    base system need not provide defaults for their
 	    &man.rc.conf.5; variables because the defaults should
@@ -512,7 +503,11 @@
 
       <callout arearefs="rcng-confdummy-msg">
 	<para>Here we use <envar>dummy_msg</envar> to actually
-	  control our script, i.e., to emit a variable message.</para>
+	  control our script, i.e., to emit a variable message.
+	  Use of a shell function is overkill here, since it only
+	  runs a single command; an equally valid alternative is:</para>
+
+	<programlisting>start_cmd="echo \"$dummy_msg\""</programlisting>
       </callout>
     </calloutlist>
   </sect1>
--- rc-scripting-modernise.diff ends here ---


>Release-Note:
>Audit-Trail:
>Unformatted: