-- Stability : provisional
-- Portability : portable
--
--- Executing a command.
+-- Executing an external command.
--
-----------------------------------------------------------------------------
-- ---------------------------------------------------------------------------
-- system
--- Computation `system cmd' returns the exit code
--- produced when the operating system processes the command `cmd'.
+{-|
+Computation @system cmd@ returns the exit code
+produced when the operating system processes the command @cmd@.
--- This computation may fail with
--- PermissionDenied
--- The process has insufficient privileges to perform the operation.
--- ResourceExhausted
--- Insufficient resources are available to perform the operation.
--- UnsupportedOperation
--- The implementation does not support system calls.
+This computation may fail with
+ * @PermissionDenied@: The process has insufficient privileges to
+ perform the operation.
+
+ * @ResourceExhausted@: Insufficient resources are available to
+ perform the operation.
+
+ * @UnsupportedOperation@: The implementation does not support
+ system calls.
+
+On Windows, 'system' is implemented using Windows's native system
+call, which ignores the @SHELL@ environment variable, and always
+passes the command to the Windows command interpreter (@CMD.EXE@ or
+@COMMAND.COM@), hence Unixy shell tricks will not work.
+-}
system :: String -> IO ExitCode
system "" = ioException (IOError Nothing InvalidArgument "system" "null command" Nothing)
system cmd =