Document the --shell semantics in the manpage

doc/watchexec.1.ronn

@@ -30,8 +30,14 @@ Change the shell used to run the command. Set to `none` to run the command direc
 
 The special value `powershell` will use Microsoft Powershell's calling convention, otherwise `SHELL -c COMMAND`.
 
+On Windows, the additional `cmd` special value uses CMD.EXE calling convention.
+
 The `none` value is especially useful in combination with `--signal`, as the signal is then send directly to the specified command. While `--shell=none` is a little more performant than the default, it prevents using shell-features like pipes and redirects.
 
+If not a special value, the string provided may contain arguments to the shell as long as that is kept simple: the string is split along whitespace, and used as per execvp(3): first is shell program, rest are arguments to the shell, then `-c` is added, and finally the `COMMAND`.
+
+See the [EXAMPLES] for uses of each of these.
+
 * `--no-shell`:
 Deprecated. Alias for `--shell=none`.
 
@@ -126,3 +132,22 @@ Watch lib and src directories for changes, rebuilding each time:
 
     $ watchexec -w lib -w src make
 
+Use without shell:
+
+    $ watchexec -n -- zsh -x -o shwordsplit scr
+
+Use with powershell (default on windows from 2.0):
+
+    $ watchexec --shell=powershell -- test-connection localhost
+
+Use with cmd (default on windows until 2.0):
+
+    $ watchexec --shell=cmd -- dir
+
+Use with a different unix shell:
+
+    $ watchexec --shell=bash -- 'echo $BASH_VERSION'
+
+Use with a unix shell and options:
+
+    $ watchexec --shell='zsh -x -o shwordsplit' -- scr

src/config.rs

@@ -26,7 +26,7 @@ use crate::run::OnBusyUpdate;
 pub struct Config {
     /// Command to execute.
     ///
-    /// When `shell` is [`Shell::None`], this is expected to be in “popen3”
+    /// When `shell` is [`Shell::None`], this is expected to be in “execvp(3)”
     /// format: first program, rest arguments. Otherwise, all elements will be
     /// joined together with a single space and passed to the shell. More
     /// control can then be obtained by providing a 1-element vec, and doing

src/process.rs

@@ -24,7 +24,7 @@ pub enum Shell {
     /// This means two things:
     /// - the program is invoked with `-c` followed by the command, and
     /// - the string will be split on space, and the resulting vec used as
-    ///   popen3 arguments: first is the shell program, rest are additional
+    ///   execvp(3) arguments: first is the shell program, rest are additional
     ///   arguments (which come before the `-c` mentioned above). This is a very
     ///   simplistic approach deliberately: it will not support quoted
     ///   arguments, for example. Use [`Shell::None`] with a custom command vec