[DOC] refine about process creations

process.c

@@ -3114,7 +3114,9 @@ NORETURN(static VALUE f_exec(int c, const VALUE *a, VALUE _));
  *
  *    Sat Aug 26 09:38:00 AM CDT 2023
  *
- *  Ruby invokes the executable directly, with no shell and no shell expansion:
+ *  Ruby invokes the executable directly.
+ *  This form does not use the shell;
+ *  see {Arguments args}[rdoc-ref:Process@Arguments+args] for caveats.
  *
  *    exec('doesnt_exist') # Raises Errno::ENOENT
  *
@@ -4820,7 +4822,9 @@ rb_spawn(int argc, const VALUE *argv)
  *    system('foo')           # => nil
  *    $?                      # => #<Process::Status: pid 645608 exit 127>
  *
- *  Ruby invokes the executable directly, with no shell and no shell expansion:
+ *  Ruby invokes the executable directly.
+ *  This form does not use the shell;
+ *  see {Arguments args}[rdoc-ref:Process@Arguments+args] for caveats.
  *
  *    system('doesnt_exist') # => nil
  *
@@ -4972,28 +4976,20 @@ rb_f_system(int argc, VALUE *argv, VALUE _)
  *
  *  Argument +exe_path+ is one of the following:
  *
- *  - The string path to an executable to be called:
+ *  - The string path to an executable to be called.
+ *  - A 2-element array containing the path to an executable to be called,
+ *    and the string to be used as the name of the executing process.
  *
  *      spawn('/usr/bin/date') # Path to date on Unix-style system.
  *      Process.wait
  *
  *    Output:
  *
- *      Thu Aug 31 10:06:48 AM CDT 2023
- *
- *  - A 2-element array containing the path to an executable
- *    and the string to be used as the name of the executing process:
- *
- *      pid = spawn(['sleep', 'Hello!'], '1') # 2-element array.
- *      p `ps -p #{pid} -o command=`
- *
- *    Output:
- *
- *      "Hello! 1\n"
+ *      Mon Aug 28 11:43:10 AM CDT 2023
  *
  *  Ruby invokes the executable directly.
  *  This form does not use the shell;
- *  see below for caveats.
+ *  see {Arguments args}[rdoc-ref:Process@Arguments+args] for caveats.
  *
  *  If one or more +args+ is given, each is an argument or option
  *  to be passed to the executable:
@@ -5008,14 +5004,6 @@ rb_f_system(int argc, VALUE *argv, VALUE _)
  *    C*
  *    hello world
  *
- *  The 'cmdname, arg1, ...' form does not use the shell. However,
- *  on different OSes, different things are provided as built-in
- *  commands. An example of this is 'echo', which is a built-in
- *  on Windows, but is a normal program on Linux and Mac OS X.
- *  This means that `Process.spawn 'echo', '%Path%'` will display
- *  the contents of the `%Path%` environment variable on Windows,
- *  but `Process.spawn 'echo', '$PATH'` prints the literal '$PATH'.
- *
  *  Raises an exception if the new process could not execute.
  */
 
@@ -8851,7 +8839,7 @@ proc_warmup(VALUE _)
  *   or if it contains one or more meta characters.
  * - +exe_path+ otherwise.
  *
- * <b>Argument +command_line+</b>
+ * ==== Argument +command_line+
  *
  * \String argument +command_line+ is a command line to be passed to a shell;
  * it must begin with a shell reserved word, begin with a special built-in,
@@ -8873,22 +8861,75 @@ proc_warmup(VALUE _)
  *
  * See {Execution Shell}[rdoc-ref:Process@Execution+Shell] for details about the shell.
  *
- * <b>Argument +exe_path+</b>
+ * ==== Argument +exe_path+
  *
  * Argument +exe_path+ is one of the following:
  *
- * - The string path to an executable to be called.
- * - A 2-element array containing the path to an executable to be called,
- *   and the string to be used as the name of the executing process.
+ * - The string path to an executable to be called:
+ *
+ *   Example:
+ *
+ *     system('/usr/bin/date') # => true # Path to date on Unix-style system.
+ *     system('foo')           # => nil  # Command execlution failed.
+ *
+ *   Output:
+ *
+ *     Thu Aug 31 10:06:48 AM CDT 2023
+ *
+ *   A path or command name containing spaces without arguments cannot
+ *   be distinguished from +command_line+ above, so you must quote or
+ *   escape the entire command name using a shell in platform
+ *   dependent manner, or use the array form below.
+ *
+ * - A 2-element array containing the path to an executable
+ *   and the string to be used as the name of the executing process:
+ *
+ *   Example:
+ *
+ *     pid = spawn(['sleep', 'Hello!'], '1') # 2-element array.
+ *     p `ps -p #{pid} -o command=`
+ *
+ *   Output:
+ *
+ *     "Hello! 1\n"
+ *
+ * === Arguments +args+
+ *
+ * If +command_line+ does not contain shell meta characters except for
+ * spaces and tabs, or +exe_path+ is given, Ruby invokes the
+ * executable directly.  This form does not use the shell:
+ *
+ *   spawn("doesnt_exist")       # Raises Errno::ENOENT
+ *   spawn("doesnt_exist", "\n") # Raises Errno::ENOENT
+ *
+ *   spawn("doesnt_exist\n")     # => false
+ *   # sh: 1: doesnot_exist: not found
+ *
+ * The error message is from a shell and would vary depending on your
+ * system.
+ *
+ * If one or more +args+ is given after +exe_path+, each is an
+ * argument or option to be passed to the executable:
  *
  * Example:
  *
- *   system('/usr/bin/date') # => true # Path to date on Unix-style system.
- *   system('foo')           # => nil  # Command failed.
+ *   system('echo', '<', 'C*', '|', '$SHELL', '>')   # => true
  *
  * Output:
  *
- *   Mon Aug 28 11:43:10 AM CDT 2023
+ *   < C* | $SHELL >
+ *
+ * However, there are exceptions on Windows.  See {Execution Shell on
+ * Windows}[rdoc-ref:Process@Execution+Shell+on+Windows].
+ *
+ * If you want to invoke a path containing spaces with no arguments
+ * without shell, you will need to use a 2-element array +exe_path+.
+ *
+ * Example:
+ *
+ *   path = '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'
+ *   spawn(path) # Raises Errno::ENOENT; No such file or directory - /Applications/Google
+ *   spawn([path] * 2)
  *
  * === Execution Options
  *
@@ -9023,21 +9064,48 @@ proc_warmup(VALUE _)
  * === Execution Shell
  *
  * On a Unix-like system, the shell invoked is <tt>/bin/sh</tt>;
- * otherwise the shell invoked is determined by environment variable
- * <tt>ENV['RUBYSHELL']</tt>, if defined, or <tt>ENV['COMSPEC']</tt> otherwise.
- *
- * Except for the +COMSPEC+ case,
  * the entire string +command_line+ is passed as an argument
  * to {shell option -c}[https://pubs.opengroup.org/onlinepubs/9699919799.2018edition/utilities/sh.html].
  *
  * The shell performs normal shell expansion on the command line:
  *
- *   spawn('echo C*') # => 799139
- *   Process.wait     # => 799139
+ * Example:
+ *
+ *   system('echo $SHELL: C*') # => true
+ *
+ * Output:
+ *
+ *   /bin/bash: CONTRIBUTING.md COPYING COPYING.ja
+ *
+ * === Execution Shell on Windows
+ *
+ * On Windows, the shell invoked is determined by environment variable
+ * +RUBYSHELL+, if defined, or +COMSPEC+ otherwise; the entire string
+ * +command_line+ is passed as an argument to <tt>-c</tt> option for
+ * +RUBYSHELL+, as well as <tt>/bin/sh</tt>, and {/c
+ * option}[https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/cmd]
+ * for +COMSPEC+.  The shell is invoked automatically in the following
+ * cases:
+ *
+ * - The command is a built-in of +cmd.exe+, such as +echo+.
+ * - The executable file is a batch file; its name ends with +.bat+ or
+ *   +.cmd+.
+ *
+ * Note that the command will still be invoked as +command_line+ form
+ * even when called in +exe_path+ form, because +cmd.exe+ does not
+ * accept a script name like <tt>/bin/sh</tt> does but only works with
+ * <tt>/c</tt> option.
+ *
+ * The standard shell +cmd.exe+ performs environment variable
+ * expansion but does not have globbing functionality:
+ *
+ * Example:
+ *
+ *   system("echo %COMSPEC%: C*")' # => true
  *
  * Output:
  *
- *   CONTRIBUTING.md COPYING COPYING.ja
+ *   C:\WINDOWS\system32\cmd.exe: C*
  *
  * == What's Here
  *