From crees@bayofrum.net  Sun Oct 14 13:02:51 2012
Return-Path: <crees@bayofrum.net>
Received: from mx1.freebsd.org (mx1.freebsd.org [69.147.83.52])
	by hub.freebsd.org (Postfix) with ESMTP id 276464A1
	for <freebsd-gnats-submit@freebsd.org>; Sun, 14 Oct 2012 13:02:51 +0000 (UTC)
	(envelope-from crees@bayofrum.net)
Received: from mk-outboundfilter-2.mail.uk.tiscali.com (mk-outboundfilter-2.mail.uk.tiscali.com [212.74.114.38])
	by mx1.freebsd.org (Postfix) with ESMTP id A58398FC0A
	for <freebsd-gnats-submit@freebsd.org>; Sun, 14 Oct 2012 13:02:50 +0000 (UTC)
Received: from 212-139-242-85.dynamic.dsl.as9105.com (HELO pegasus.bayofrum.net) ([212.139.242.85])
  by smtp.pipex.tiscali.co.uk with ESMTP; 14 Oct 2012 14:02:48 +0100
Received: by pegasus.bayofrum.net (Postfix, from userid 1001)
	id 837AD4D332; Sun, 14 Oct 2012 14:02:39 +0100 (BST)
Message-Id: <20121014130239.837AD4D332@pegasus.bayofrum.net>
Date: Sun, 14 Oct 2012 14:02:39 +0100 (BST)
From: Chris Rees <utisoft@gmail.com>
Reply-To: Chris Rees <crees@FreeBSD.org>
To: FreeBSD-gnats-submit@freebsd.org
Cc:
Subject: [PATCH] Bring parts of the rc scripting guides up to date
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>Number:         172692
>Category:       docs
>Synopsis:       [PATCH] Bring parts of the rc scripting guides up to date
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    eadler
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          change-request
>Submitter-Id:   current-users
>Arrival-Date:   Sun Oct 14 13:10:00 UTC 2012
>Closed-Date:    Fri Nov 02 01:09:33 UTC 2012
>Last-Modified:  Fri Nov 02 01:09:33 UTC 2012
>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@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:
Responsible-Changed-From-To: freebsd-doc->freebsd-rc 
Responsible-Changed-By: crees 
Responsible-Changed-When: Sun Oct 14 13:19:15 UTC 2012 
Responsible-Changed-Why:  
What do you guys think? 

http://www.freebsd.org/cgi/query-pr.cgi?pr=172692 

From: Michael Telahun Makonnen <mmakonnen@gmail.com>
To: crees@FreeBSD.org
Cc:
Subject: Re: docs/172692: [PATCH] Bring parts of the rc scripting guides up to date
Date: Mon, 15 Oct 2012 19:29:04 +0300
Some minor nits:

@@ -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>

You should add the same correction to the very next sentence, which reads:

Note: While it is possible to use a shorter name internally, e.g.,  just 
msg, adding the unique prefix ${name} to all global names introduced by 
our script will save us from possible collisions with the rc.subr(8) 
namespace.


@@ -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>
-

Not sure why you felt this paragraph needed to be removed.

@@ -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>

While you are technically correct, I think you misunderstood the 
writer's intent, which was to show how an rc.conf(8) variable can be 
used in a subroutine to control the behavior of the command.  I agree 
that the example isn't a very good one (in that it doesn't depict a 
valid use case), but I think the "spirit" is correct.  Maybe you can 
suggest a better example?

Cheers,
Mike.


From: Chris Rees <crees@FreeBSD.org>
To: Michael Telahun Makonnen <mmakonnen@gmail.com>
Cc: freebsd-doc@freebsd.org, freebsd-rc@freebsd.org, freebsd-bugs@freebsd.org, 
	"bug-followup@freebsd.org" <bug-followup@freebsd.org>
Subject: Re: docs/172692: [PATCH] Bring parts of the rc scripting guides up to date
Date: Mon, 15 Oct 2012 19:26:22 +0100

 On 15/10/2012, Michael Telahun Makonnen <mmakonnen@gmail.com> wrote:
 > Some minor nits:
 >
 > -       have the same prefix: <envar>${name}</envar>.  For
 > +        have the same prefix: <envar>${name}_</envar>.  For
 >
 > You should add the same correction to the very next sentence, which reads:
 >
 > Note: While it is possible to use a shorter name internally, e.g.,  just
 
 Done, thanks!
 
 >
 >
 > @@ -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>
 > -
 >
 > Not sure why you felt this paragraph needed to be removed.
 
 Because the style is clearer and makes it much more obvious when a
 variable is having its own default value set.  In ports at least, the
 current style is to use the less verbose form.
 
 > @@ -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>
 >
 > While you are technically correct, I think you misunderstood the
 > writer's intent, which was to show how an rc.conf(8) variable can be
 > used in a subroutine to control the behavior of the command.  I agree
 > that the example isn't a very good one (in that it doesn't depict a
 > valid use case), but I think the "spirit" is correct.  Maybe you can
 > suggest a better example?
 >
 
 I think that this script is very simple by design, and making a better
 example would complicate it.  It is definitely worth pointing out the
 alternative though; it makes useful food for thought; both examples
 with a disclaimer.
 
 Thank you very much for commenting, and I feel bad that I'm fobbing
 you off.  You've raised genuine points, but I had already considered
 them.  Please keep on at me if you think I still need to do something
 about it.
 
 Chris
 
 [1] http://www.bayofrum.net/~crees/patches/rc-scripting-modernise2.diff
 
 -- 
 Chris Rees          | FreeBSD Developer
 crees@FreeBSD.org   | http://people.freebsd.org/~crees

From: Michael Telahun Makonnen <mmakonnen@gmail.com>
To: Chris Rees <crees@FreeBSD.org>
Cc: freebsd-doc@freebsd.org, freebsd-rc@freebsd.org, 
 "bug-followup@freebsd.org" <bug-followup@freebsd.org>
Subject: Re: docs/172692: [PATCH] Bring parts of the rc scripting guides up
 to date
Date: Thu, 18 Oct 2012 09:57:49 +0300

 On 10/15/2012 09:26 PM, Chris Rees wrote:
 
 >> Not sure why you felt this paragraph needed to be removed.
 >
 > Because the style is clearer and makes it much more obvious when a
 > variable is having its own default value set.  In ports at least, the
 > current style is to use the less verbose form.
 >
 
 ok
 
 >
 >> While you are technically correct, I think you misunderstood the
 >> writer's intent, which was to show how an rc.conf(8) variable can be
 >> used in a subroutine to control the behavior of the command.  I agree
 >> that the example isn't a very good one (in that it doesn't depict a
 >> valid use case), but I think the "spirit" is correct.  Maybe you can
 >> suggest a better example?
 >>
 >
 > I think that this script is very simple by design, and making a better
 > example would complicate it.  It is definitely worth pointing out the
 > alternative though; it makes useful food for thought; both examples
 > with a disclaimer.
 
 ok
 
 >
 > [1] http://www.bayofrum.net/~crees/patches/rc-scripting-modernise2.diff
 >
 
 Looks fine to me. Thanks for taking the time to update the documentation.
 
 Cheers,
 Mike.
Responsible-Changed-From-To: freebsd-rc->freebsd-doc 
Responsible-Changed-By: crees 
Responsible-Changed-When: Thu Oct 25 20:10:57 UTC 2012 
Responsible-Changed-Why:  
Glad people are OK with it-- please would someone see if they can get 
this in? 

http://www.freebsd.org/cgi/query-pr.cgi?pr=172692 
Responsible-Changed-From-To: freebsd-doc->eadler 
Responsible-Changed-By: eadler 
Responsible-Changed-When: Wed Oct 31 12:58:45 UTC 2012 
Responsible-Changed-Why:  
I'll take it. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=172692 
State-Changed-From-To: open->closed 
State-Changed-By: eadler 
State-Changed-When: Fri Nov 2 01:09:32 UTC 2012 
State-Changed-Why:  
Committed. Thanks! 

http://www.freebsd.org/cgi/query-pr.cgi?pr=172692 
>Unformatted:
