--- a/NEWS	Thu Dec 08 19:25:38 2011 -0500
+++ b/NEWS	Thu Dec 08 17:25:30 2011 -0800
@@ -154,9 +154,9 @@
 
       cut                is_duplicate_entry
       cor                polyderiv
-      corrcoef           studentize
-      __error_text__     sylvester_matrix
-      error_text
+      corrcoef           shell_cmd 
+      __error_text__     studentize
+      error_text         sylvester_matrix
 
 Summary of important user-visible changes for version 3.4.3:
 -----------------------------------------------------------

--- a/doc/interpreter/doccheck/mk_undocumented_list	Thu Dec 08 19:25:38 2011 -0500
+++ b/doc/interpreter/doccheck/mk_undocumented_list	Thu Dec 08 17:25:30 2011 -0800
@@ -120,7 +120,6 @@
 SEEK_END
 semicolon
 setenv
-shell_cmd
 toc
 triu
 unimplemented

--- a/doc/interpreter/install.txi	Thu Dec 08 19:25:38 2011 -0500
+++ b/doc/interpreter/install.txi	Thu Dec 08 17:25:30 2011 -0800
@@ -747,7 +747,7 @@
 these files without @option{-g}.
 
 @item
-Some people have reported that calls to shell_cmd and the pager do not
+Some people have reported that calls to system() and the pager do not
 work on SunOS systems.  This is apparently due to having
 @w{@code{G_HAVE_SYS_WAIT}} defined to be 0 instead of 1 when compiling
 @code{libg++}.

--- a/scripts/deprecated/module.mk	Thu Dec 08 19:25:38 2011 -0500
+++ b/scripts/deprecated/module.mk	Thu Dec 08 17:25:30 2011 -0800
@@ -24,6 +24,7 @@
   deprecated/replot.m \
   deprecated/saveimage.m \
   deprecated/setstr.m \
+  deprecated/shell_cmd.m \
   deprecated/sphcat.m \
   deprecated/spvcat.m \
   deprecated/strerror.m \

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/scripts/deprecated/shell_cmd.m	Thu Dec 08 17:25:30 2011 -0800
@@ -0,0 +1,68 @@
+## Copyright (C) 2011 Rik Wehbring
+##
+## This file is part of Octave.
+##
+## Octave is free software; you can redistribute it and/or modify it
+## under the terms of the GNU General Public License as published by
+## the Free Software Foundation; either version 3 of the License, or (at
+## your option) any later version.
+##
+## Octave is distributed in the hope that it will be useful, but
+## WITHOUT ANY WARRANTY; without even the implied warranty of
+## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+## General Public License for more details.
+##
+## You should have received a copy of the GNU General Public License
+## along with Octave; see the file COPYING.  If not, see
+## <http://www.gnu.org/licenses/>.
+
+## "-*- texinfo -*-
+## @deftypefn  {Built-in Function} {} shell_cmd (@var{string})
+## @deftypefnx {Built-in Function} {} shell_cmd (@var{string}, @var{return_output})
+## @deftypefnx {Built-in Function} {} shell_cmd (@var{string}, @var{return_output}, @var{type})
+## @deftypefnx {Built-in Function} {[@var{status}, @var{output}] =} shell_cmd (@dots{})
+## @deftypefnx {Built-in Function} {[@var{status}, @var{output}] =} shell_cmd (@var{string}, @var{return_output}, @var{type})
+## Execute a shell command specified by @var{string}.
+## If the optional argument @var{type} is "async", the process
+## is started in the background and the process id of the child process
+## is returned immediately.  Otherwise, the process is started and
+## Octave waits until it exits.  If the @var{type} argument is omitted, it
+## defaults to a value of "sync".
+## 
+## If the optional argument @var{return_output} is true and the subprocess
+## is started synchronously, or if @var{shell_cmd} is called with one input
+## argument and one or more output arguments, then the output from the command
+## is returned.  Otherwise, if the subprocess is executed synchronously, its
+## output is sent to the standard output.
+##
+## The @code{shell_cmd} function can return two values.  The first is the
+## exit status of the command and the second is any output from the
+## command that was written to the standard output stream.  For example,
+## 
+## @example
+## [status, output] = shell_cmd ("echo foo; exit 2");
+## @end example
+## 
+## @noindent
+## will set the variable @code{output} to the string @samp{foo}, and the
+## variable @code{status} to the integer @samp{2}.
+## 
+## For commands run asynchronously, @var{status} is the process id of the
+## command shell that is started to run the command.
+## @seealso{system, unix, dos}
+## @end deftypefn
+
+## Deprecated in version 3.6
+
+function [status, output] = shell_cmd (varargin)
+  persistent warned = false;
+  if (! warned)
+    warned = true;
+    warning ("Octave:deprecated-function",
+             "shell_cmd is obsolete and will be removed from a future version of Octave; please use system instead");
+  endif
+
+  [status, output] = system (varargin{:});
+
+endfunction
+

--- a/scripts/miscellaneous/dos.m	Thu Dec 08 19:25:38 2011 -0500
+++ b/scripts/miscellaneous/dos.m	Thu Dec 08 17:25:30 2011 -0800
@@ -17,14 +17,16 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn  {Function File} {[@var{status}, @var{text}] =} dos (@var{command})
-## @deftypefnx {Function File} {[@var{status}, @var{text}] =} dos (@var{command}, "-echo")
+## @deftypefn  {Function File} {} dos ("@var{command}")
+## @deftypefnx {Function File} {@var{status} =} dos ("@var{command}")
+## @deftypefnx {Function File} {[@var{status}, @var{text}] =} dos ("@var{command"})
+## @deftypefnx {Function File} {[@dots{}] =} dos ("@var{command}", "-echo")
 ## Execute a system command if running under a Windows-like operating
 ## system, otherwise do nothing.  Return the exit status of the program
-## in @var{status} and any output sent to the standard output in
-## @var{text}.  If the optional second argument @code{"-echo"} is given,
-## then also send the output from the command to the standard output.
-## @seealso{unix, isunix, ispc, system}
+## in @var{status} and any output from the command in @var{text}.
+## When called with no output argument, or the "-echo" argument is
+## given, then @var{text} is also sent to standard output.
+## @seealso{unix, system, isunix, ispc}
 ## @end deftypefn
 
 ## Author: octave-forge ???
@@ -42,3 +44,28 @@
   endif
 
 endfunction
+
+
+%!test
+%! cmd = ls_command ();
+%! old_wstate = warning ("query");
+%! warning ("off", "Octave:undefined-return-values");
+%! unwind_protect
+%!   [status, output] = dos (cmd);
+%! unwind_protect_cleanup
+%!   warning (old_wstate); 
+%! end_unwind_protect
+%!
+%! if (ispc () && ! isunix ())
+%!   [status, output] = dos (cmd);
+%!   assert (status, 0);
+%!   assert (ischar (output));
+%!   assert (! isempty (output));
+%! else
+%!   assert (status, []);
+%!   assert (output, []);
+%! endif
+
+%!error dos ()
+%!error dos (1, 2, 3)
+

--- a/scripts/miscellaneous/unix.m	Thu Dec 08 19:25:38 2011 -0500
+++ b/scripts/miscellaneous/unix.m	Thu Dec 08 17:25:30 2011 -0800
@@ -17,14 +17,16 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn  {Function File} {[@var{status}, @var{text}] =} unix (@var{command})
-## @deftypefnx {Function File} {[@var{status}, @var{text}] =} unix (@var{command}, "-echo")
+## @deftypefn  {Function File} {} unix ("@var{command}")
+## @deftypefnx {Function File} {@var{status} =} unix ("@var{command}")
+## @deftypefnx {Function File} {[@var{status}, @var{text}] =} unix ("@var{command}")
+## @deftypefnx {Function File} {[@dots{}] =} unix ("@var{command}", "-echo")
 ## Execute a system command if running under a Unix-like operating
 ## system, otherwise do nothing.  Return the exit status of the program
-## in @var{status} and any output sent to the standard output in
-## @var{text}.  If the optional second argument @code{"-echo"} is given,
-## then also send the output from the command to the standard output.
-## @seealso{isunix, ispc, system}
+## in @var{status} and any output from the command in @var{text}.
+## When called with no output argument, or the "-echo" argument is
+## given, then @var{text} is also sent to standard output.
+## @seealso{dos, system, isunix, ispc}
 ## @end deftypefn
 
 ## Author: octave-forge ???
@@ -42,3 +44,27 @@
   endif
 
 endfunction
+
+
+%!test
+%! cmd = ls_command ();
+%! old_wstate = warning ("query");
+%! warning ("off", "Octave:undefined-return-values");
+%! unwind_protect
+%!   [status, output] = unix (cmd);
+%! unwind_protect_cleanup
+%!   warning (old_wstate); 
+%! end_unwind_protect
+%!
+%! if (isunix ())
+%!   assert (status, 0);
+%!   assert (ischar (output));
+%!   assert (! isempty (output));
+%! else
+%!   assert (status, []);
+%!   assert (output, []);
+%! endif
+
+%!error unix ()
+%!error unix (1, 2, 3)
+

--- a/src/toplev.cc	Thu Dec 08 19:25:38 2011 -0500
+++ b/src/toplev.cc	Thu Dec 08 17:25:30 2011 -0800
@@ -827,8 +827,8 @@
       else
         cmd_status = 127;
 
+      retval(1) = output_buf.str ();
       retval(0) = cmd_status;
-      retval(1) = output_buf.str ();
     }
   else
     error ("unable to start subprocess for `%s'", cmd_str.c_str ());
@@ -840,31 +840,36 @@
 
 DEFUN (system, args, nargout,
   "-*- texinfo -*-\n\
-@deftypefn  {Built-in Function} {[@var{status}, @var{output}]} system (@var{string}, @var{return_output}, @var{type})\n\
-@deftypefnx {Built-in Function} {[@var{status}, @var{output}]} shell_cmd (@var{string}, @var{return_output}, @var{type})\n\
+@deftypefn  {Built-in Function} {} system (\"@var{string}\")\n\
+@deftypefnx {Built-in Function} {} system (\"@var{string}\", @var{return_output})\n\
+@deftypefnx {Built-in Function} {} system (\"@var{string}\", @var{return_output}, @var{type})\n\
+@deftypefnx {Built-in Function} {[@var{status}, @var{output}] =} system (@dots{})\n\
 Execute a shell command specified by @var{string}.\n\
-If the optional argument @var{type} is @code{\"async\"}, the process\n\
-is started in the background and the process id of the child process\n\
-is returned immediately.  Otherwise, the process is started, and\n\
-Octave waits until it exits.  If the @var{type} argument is omitted, a\n\
-value of @code{\"sync\"} is assumed.\n\
+If the optional argument @var{type} is \"async\", the process\n\
+is started in the background and the process ID of the child process\n\
+is returned immediately.  Otherwise, the child process is started and\n\
+Octave waits until it exits.  If the @var{type} argument is omitted, it\n\
+defaults to the value \"sync\".\n\
 \n\
-If the optional argument @var{return_output} is true and the subprocess\n\
-is started synchronously, or if @var{system} is called with one input\n\
-argument and one or more output arguments, the output from the command\n\
-is returned.  Otherwise, if the subprocess is executed synchronously, its\n\
-output is sent to the standard output.  To send the output of a command\n\
-executed with @code{system} through the pager, use a command like\n\
+If @var{system} is called with one or more output arguments, or if the\n\
+optional argument @var{return_output} is true and the subprocess is started\n\
+synchronously, then the output from the command is returned as a variable.  \n\
+Otherwise, if the subprocess is executed synchronously, its output is sent\n\
+to the standard output.  To send the output of a command executed with\n\
+@code{system} through the pager, use a command like\n\
 \n\
 @example\n\
-disp (system (cmd, 1));\n\
+@group\n\
+[output, text] = system (\"cmd\");\n\
+disp (text);\n\
+@end group\n\
 @end example\n\
 \n\
 @noindent\n\
 or\n\
 \n\
 @example\n\
-printf (\"%s\\n\", system (cmd, 1));\n\
+printf (\"%s\\n\", nthargout (2, \"system\", \"cmd\"));\n\
 @end example\n\
 \n\
 The @code{system} function can return two values.  The first is the\n\
@@ -881,6 +886,7 @@
 \n\
 For commands run asynchronously, @var{status} is the process id of the\n\
 command shell that is started to run the command.\n\
+@seealso{unix, dos}\n\
 @end deftypefn")
 {
   octave_value_list retval;
@@ -1011,20 +1017,16 @@
   return retval;
 }
 
-DEFALIAS (shell_cmd, system);
-
 /*
-%!error (system ());
-%!error (system (1, 2, 3));
 %!test
-%! if (ispc ())
-%!   cmd = "dir";
-%! else
-%!   cmd = "ls";
-%! endif
+%! cmd = ls_command ();
 %! [status, output] = system (cmd);
+%! assert (status, 0);
 %! assert (ischar (output));
 %! assert (! isempty (output));
+
+%!error system ()
+%!error system (1, 2, 3)
 */
 
 // FIXME -- this should really be static, but that causes