bug#71081: 30.0.50; shell-command-on-region outputs boilerplate text on Windows

[Eli Zaretskii]

> From: Ihor Radchenko <yantar92@posteo.net>
> Cc: dmitry@gutov.dev, 71081@debbugs.gnu.org, matt@excalamus.com
> Date: Thu, 23 May 2024 14:00:44 +0000
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> On Windows, it yields
> >> 
> >> "foo"
> >
> > Yes, because the Windows shell doesn't support command lines with
> > embedded newlines, so it ignores everything past the first newline.
> > (Actually, there are complicated tricks to do that, but I'll spare
> > you.)
> 
> Should it be documented in the docstring of `shell-command-to-string'?

We could, but IMO such tangential information belongs to the manual,
not to the doc string.  We should also somehow avoid the slippery
slope of describing all the differences between the Posix shells and
the Windows shell.  E.g., newlines are also not allowed in Windows
file names, but we don't mention that in doc strings of every function
that deals with file names.

> Currently, it only mentions `shell-quote-argument' and the current
> behaviour is not expected - there is nothing indicating that one should
> be careful about newlines (or any other characters passed to system
> shell).

Characters special to a shell always need special attention.  And
which characters are special to a given shell depends on the shell.
Emacs supports special characters for a couple of widely-used shells,
but not for all of them.

> > Instead, you should do this on Windows:
> >
> >   (shell-command-to-string "echo foo && echo bar")
> >
> > This is the documented method of invoking cmd.exe with multiple
> > commands.
> 
> Maybe. But `shell-command-on-region' does work with multi-line commands,

No, it works with multi-line _regions_, since the region is sent to
the shell command as input to process.

> Why would anyone assume that `shell-command-to-string' is
> passed as an argument to cmd.exe and not piped as input?

Because the doc string says so:

  Execute shell command COMMAND and return its output as a string.

"Execute COMMAND" means run it as "SHELL -c COMMAND", in any
reasonable interpretation.  Anything else is not the usual way of
running commands.

> more over, on Linux, different shells have different behaviors wrt
> input/command argument/script file).

Same on Windows.  Try PowerShell some day.  Does it mean we need to
document all of that in our documentation?