Move the paragraphs on run_rc_command syntax and properties to above

the example so that a reader can understand it better.

Note current $* misuse in run_rc_command so that a reader who understands
$@ and experiments with its application to run_rc_command isn't confused.

Suggested by:	dougb (1st explicitly and 2nd implicitly)

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

@@ -1187,8 +1187,28 @@ run_rc_command "$1"</programlisting>
 
     <para>Fortunately, &man.rc.subr.8; allows for passing any number
       of arguments to script's methods (within the system limits).
-      Due to that, the changes in the script itself can be minimal.
+      Due to that, the changes in the script itself can be minimal.</para>
-      To illustrate this opportunity, let us modify the primitive
+    
+    <para>How can &man.rc.subr.8; gain
+      access to the extra command-line arguments.  Should it just
+      grab them directly?  Not by any means.  Firstly, an &man.sh.1;
+      function has no access to the positional parameters of
+      its caller, but &man.rc.subr.8; is just a sack of such
+      functions.  Secondly, the good manner of
+      <filename>rc.d</filename> dictates that it is for the
+      main script to decide which arguments are to be passed
+      to its methods.</para>
+
+    <para>So the approach adopted by &man.rc.subr.8; is as follows:
+      <function>run_rc_command</function> passes on all its
+      arguments but the first one to the respective method verbatim.
+      The first, omitted, argument is the name of the method itself:
+      <option>start</option>, <option>stop</option>, etc.  It will
+      be shifted out by <function>run_rc_command</function>,
+      so what is <envar>$2</envar> in the original command line will
+      be presented as <envar>$1</envar> to the method, and so on.</para>
+
+    <para>To illustrate this opportunity, let us modify the primitive
       dummy script so that its messages depend on the additional
       arguments supplied.  Here we go:</para>
 
@@ -1264,23 +1284,10 @@ A ghost gives you a kiss and whispers: Once I was Etaoin Shrdlu...</screen>
       </callout>
 
       <callout arearefs="rcng-args-all">
-	<para>The only question left is how &man.rc.subr.8; can gain
+	<para>If we want just to pass all extra arguments to
-	  access to the extra command-line arguments.  Should it just
-	  grab them directly?  Not by any means.  Firstly, an &man.sh.1;
-	  function has no access to the positional parameters of
-	  its caller, but &man.rc.subr.8; is just a sack of such
-	  functions.  Secondly, the good manner of
-	  <filename>rc.d</filename> dictates that it is for the
-	  main script to decide which arguments are to be passed
-	  to its methods.</para>
-
-	<para>So the approach adopted by &man.rc.subr.8; is as follows:
-	  <function>run_rc_command</function> passes on all its
-	  arguments but the first one to the respective method verbatim.
-	  The first, omitted, argument is the name of the method itself.
-	  Consequently, if we want just to pass all extra arguments to
 	  any method, we can merely substitute <literal>"$@"</literal>
-	  for <literal>"$1"</literal> in the last line of our script.</para>
+	  for <literal>"$1"</literal> in the last line of our script,
+	  where we invoke <function>run_rc_command</function>.</para>
 
 	<important>
 	  <para>An &man.sh.1; programmer ought to understand the
@@ -1293,11 +1300,13 @@ A ghost gives you a kiss and whispers: Once I was Etaoin Shrdlu...</screen>
 	    buggy and insecure scripts.</para>
 	</important>
 
-	<para>The <function>run_rc_command</function> function will
+	<note>
-	  consume its first argument to find the method.  Hence an
+	  <para>Currently <function>run_rc_command</function> may
-	  apparent shift by one argument:  What is <envar>$2</envar>
+	    have a bug that prevents it from keeping the original
-	  in the command line will be presented as <envar>$1</envar>
+	    boundaries between arguments.  That is, arguments with
-	  to the method, and so on.</para>
+	    embedded whitespace may not be processed correctly.
+	    The bug stems from <envar>$*</envar> misuse.</para>
+	</note>
       </callout>
     </calloutlist>
   </sect1>