bug#18409: 24.3; call-process-shell-command doc

bug#18409: 24.3; call-process-shell-command doc

[Devon Sean McCullough]

Make the rest args easier to spot in the documentation

--- lisp/subr.el.~1~	2014-09-04 11:46:00.000000000 -0400
+++ lisp/subr.el	2014-09-04 11:48:31.000000000 -0400
@@ -3027,7 +3027,7 @@
t (mix it with ordinary output), or a file name string.

Fourth arg DISPLAY non-nil means redisplay buffer as output is inserted.
-Remaining arguments are strings passed as additional arguments for COMMAND.
+Remaining ARGS are strings passed as additional arguments for COMMAND.
Wildcards and redirection are handled as usual in the shell.

If BUFFER is 0, `call-process-shell-command' returns immediately with value nil.

bug#18409: 24.3; call-process-shell-command doc

[Stefan Monnier]

> Make the rest args easier to spot in the documentation

On the contrary, this `args' is just asking for trouble.  Don't use it.

We obsoleted it for start-process-shell-command in Emacs-23 and forgot
to do it for the call-process variant, which I just fixed with the
patch below.

Thanks for bringing it up.


        Stefan


=== modified file 'etc/NEWS'
--- etc/NEWS	2014-09-03 16:13:17 +0000
+++ etc/NEWS	2014-09-05 01:17:23 +0000
@@ -200,6 +200,9 @@
 \f
 * Lisp Changes in Emacs 24.5
 
+*** call-process-shell-command and process-file-shell-command
+don't take "&rest args" an more.
+
 ** New function `funcall-interactively', which works like `funcall'
 but makes `called-interactively-p' treat the function as (you guessed it)
 called interactively.

=== modified file 'lisp/ChangeLog'
--- lisp/ChangeLog	2014-09-05 01:04:47 +0000
+++ lisp/ChangeLog	2014-09-05 01:19:21 +0000
@@ -1,3 +1,10 @@
+2014-09-05  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+	* subr.el (call-process-shell-command, process-file-shell-command):
+	Make the `args' obsolete (bug#18409).
+	(start-process-shell-command, start-file-process-shell-command):
+	Use `declare'.
+
 2014-09-05  Jay Belanger  <jay.p.belanger@gmail.com>
 
 	* calc/calc-forms.el (math-normalize-hms): Do a better check for

=== modified file 'lisp/subr.el'
--- lisp/subr.el	2014-09-03 04:21:40 +0000
+++ lisp/subr.el	2014-09-05 01:12:43 +0000
@@ -2877,23 +2877,21 @@
 An old calling convention accepted any number of arguments after COMMAND,
 which were just concatenated to COMMAND.  This is still supported but strongly
 discouraged."
+  (declare (advertised-calling-convention (name buffer command) "23.1"))
    ;; We used to use `exec' to replace the shell with the command,
    ;; but that failed to handle (...) and semicolon, etc.
   (start-process name buffer shell-file-name shell-command-switch
 		 (mapconcat 'identity args " ")))
-(set-advertised-calling-convention 'start-process-shell-command
-                                   '(name buffer command) "23.1")
 
 (defun start-file-process-shell-command (name buffer &rest args)
   "Start a program in a subprocess.  Return the process object for it.
 Similar to `start-process-shell-command', but calls `start-file-process'."
+  (declare (advertised-calling-convention (name buffer command) "23.1"))
   (start-file-process
    name buffer
    (if (file-remote-p default-directory) "/bin/sh" shell-file-name)
    (if (file-remote-p default-directory) "-c" shell-command-switch)
    (mapconcat 'identity args " ")))
-(set-advertised-calling-convention 'start-file-process-shell-command
-                                   '(name buffer command) "23.1")
 
 (defun call-process-shell-command (command &optional infile buffer display
 					   &rest args)
@@ -2909,13 +2907,18 @@
 t (mix it with ordinary output), or a file name string.
 
 Fourth arg DISPLAY non-nil means redisplay buffer as output is inserted.
-Remaining arguments are strings passed as additional arguments for COMMAND.
 Wildcards and redirection are handled as usual in the shell.
 
 If BUFFER is 0, `call-process-shell-command' returns immediately with value nil.
 Otherwise it waits for COMMAND to terminate and returns a numeric exit
 status or a signal description string.
-If you quit, the process is killed with SIGINT, or SIGKILL if you quit again."
+If you quit, the process is killed with SIGINT, or SIGKILL if you quit again.
+
+An old calling convention accepted any number of arguments after DISPLAY,
+which were just concatenated to COMMAND.  This is still supported but strongly
+discouraged."
+  (declare (advertised-calling-convention
+            (command &optional infile buffer display) "24.5"))
   ;; We used to use `exec' to replace the shell with the command,
   ;; but that failed to handle (...) and semicolon, etc.
   (call-process shell-file-name
@@ -2927,6 +2930,8 @@
 					   &rest args)
   "Process files synchronously in a separate process.
 Similar to `call-process-shell-command', but calls `process-file'."
+  (declare (advertised-calling-convention
+            (command &optional infile buffer display) "24.5"))
   (process-file
    (if (file-remote-p default-directory) "/bin/sh" shell-file-name)
    infile buffer display