bug#22335: 24.2; Documentation of shell-command-on-region incorrect?

[Paul Hilfinger]

This bug report will be sent to the Bug-GNU-Emacs mailing list
and the GNU bug tracker at debbugs.gnu.org.  Please check that
the From: line contains a valid email address.  After a delay of up
to one day, you should receive an acknowledgement at that address.

Please write in English if possible, as the Emacs maintainers
usually do not have translators for other languages.

Please describe exactly what actions triggered the bug, and
the precise symptoms of the bug.  If you can, give a recipe
starting from `emacs -Q':

The current documentation for shell-command-on-region says that 

    If the optional fourth argument OUTPUT-BUFFER is non-nil,
    that says to put the output in some other buffer.
    If OUTPUT-BUFFER is a buffer or buffer name, put the output there.
    If OUTPUT-BUFFER is not a buffer and not nil,
    insert output in the current buffer.
    In either case, the output is inserted after point (leaving mark after it).

    If REPLACE, the optional fifth argument, is non-nil, that means insert
    the output in place of text from START to END, putting point and mark
    around it.

This seems to suggest that if REPLACE is nil, the initial contents of
OUTPUT-BUFFER are retained.  However, this does not seem to be the
behavior of the command at all.  Indeed, in the defun for
shell-command-on-region, there appears:

    (if (or replace
            (and output-buffer
                 (not (or (bufferp output-buffer) (stringp output-buffer)))))
        ;; Replace specified region with output from command.
        (let ((swap (and replace (< start end))))
          ;; Don't muck with mark unless REPLACE says we should.
          (goto-char start)
          (and replace (push-mark (point) 'nomsg))
          (setq exit-status
                (call-process-region start end shell-file-name t
                                     (if error-file
                                         (list t error-file)
                                       t)
                                     nil shell-command-switch command))

which would indeed seem to delete the existing text unconditionally.

Assuming the current behavior is intentional, the purpose of REPLACE
seems to be only to affect the point and mark, which makes its name a
bit misleading.

Since I don't know the original intent of the command, I won't suggest a
fix.  It seems to me, though, that either the documentation or code
should change---probably the former, since I suspect the communal code
base has come to rely on the current behavior.

P. Hilfinger


If Emacs crashed, and you have the Emacs process in the gdb debugger,
please include the output from the following gdb commands:
    `bt full' and `xbacktrace'.
For information about debugging Emacs, please read the file
/usr/sww/pkg/emacs-24.2/share/emacs/24.2/etc/DEBUG.


In GNU Emacs 24.2.1 (i386-pc-solaris2.10, X toolkit, Xaw3d scroll bars)
 of 2012-09-17 on idev10
Windowing system distributor `Sun Microsystems, Inc.', version 11.0.10300000
Configured using:
 `configure '--prefix=/usr/sww/pkg/emacs-24.2' 'CC=gcc' 'CFLAGS='
'LDFLAGS=-R/usr/sww/lib -L/usr/sww/lib' 'CPPFLAGS=-I/usr/sww/include''

Important settings:
  value of $LC_ALL: nil
  value of $LC_COLLATE: nil
  value of $LC_CTYPE: nil
  value of $LC_MESSAGES: nil
  value of $LC_MONETARY: nil
  value of $LC_NUMERIC: nil
  value of $LC_TIME: nil
  value of $LANG: C
  value of $XMODIFIERS: nil
  locale-coding-system: nil
  default enable-multibyte-characters: t

Major mode: Completion List

Minor modes in effect:
  shell-dirtrack-mode: t
  diff-auto-refine-mode: t
  tooltip-mode: t
  mouse-wheel-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  blink-cursor-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  line-number-mode: t
  transient-mark-mode: t

Recent input:
e s <return> C-h f c a l l - r p o <backspace> <backspace> 
<backspace> o <backspace> p r o c e s s - r e g i <tab> 
<return> C-x o C-z C-z C-z C-g C-g C-h f ? C-x o C-s 
b u g C-s C-s C-s C-s C-s C-s C-s C-s C-s C-s C-s C-s 
C-s C-s C-s C-s C-s C-s C-s C-s C-s C-s C-s C-s C-s 
C-s C-s C-a C-s - b u g C-a C-s C-s C-s C-s C-s C-s 
C-s C-s C-s C-s C-s C-p M-x r e p o r t - e m <tab> 
<return> D o c u m e n t a i <backspace> t i o n SPC 
o f SPC s h e l l - c o m m o n - <backspace> <backspace> 
<backspace> a n d - o n - r e g i o n SPC i n c o r 
r e c t ? <return> T h e SPC c o <backspace> <backspace> 
d o u c v m n <backspace> <backspace> <backspace> <backspace> 
<backspace> c u e m n t a t i o n SPC C-a C-k C-k C-k 
C-x u C-z C-z C-z C-z C-z C-z C-z C-v C-v C-v C-v C-v 
C-v M-v M-v M-v M-v M-v M-v C-p C-p C-p C-p C-p C-p 
C-p C-p C-p C-p C-p C-p C-p C-p C-p C-p C-p C-p C-p 
C-p C-p C-p C-p C-p C-p C-p C-n C-n C-n C-n C-n C-n 
C-n C-n C-n C-n C-p C-p C-p C-p C-p C-p C-p C-p C-n 
C-n C-n C-n C-p C-p C-p C-p C-n C-n C-n C-p C-p C-n 
C-x k <return> y e s <return> M-x r e p o r t - e m 
<tab> <return>

Recent messages:
Checking 148 files in 
/usr/sww/pkg/emacs-24.2/share/emacs/24.2/lisp/emacs-lisp...
Checking 24 files in /usr/sww/pkg/emacs-24.2/share/emacs/24.2/lisp/cedet...
Checking 57 files in /usr/sww/pkg/emacs-24.2/share/emacs/24.2/lisp/calendar...
Checking 87 files in /usr/sww/pkg/emacs-24.2/share/emacs/24.2/lisp/calc...
Checking 65 files in /usr/sww/pkg/emacs-24.2/share/emacs/24.2/lisp/obsolete...
Checking 1 files in /usr/sww/pkg/emacs-24.2/share/emacs/24.2/leim...
Checking 85 files in ~/lib/emacs/lisp/calc-2.02f...
Checking for load-path shadows...done
Undo!
scroll-up-command: End of buffer

Load-path shadows:
~/lib/emacs/lisp/fill hides 
/usr/sww/pkg/emacs-24.2/share/emacs/24.2/lisp/textmodes/fill
/usr/sww/pkg/emacs-24.2/share/emacs/24.2/lisp/calc/calc hides 
~/lib/emacs/lisp/calc-2.02f/calc
/usr/sww/pkg/emacs-24.2/share/emacs/24.2/lisp/calc/calc-aent hides 
~/lib/emacs/lisp/calc-2.02f/calc-aent
/usr/sww/pkg/emacs-24.2/share/emacs/24.2/lisp/calc/calc-yank hides 
~/lib/emacs/lisp/calc-2.02f/calc-yank
/usr/sww/pkg/emacs-24.2/share/emacs/24.2/lisp/calc/calc-vec hides 
~/lib/emacs/lisp/calc-2.02f/calc-vec
/usr/sww/pkg/emacs-24.2/share/emacs/24.2/lisp/calc/calc-units hides 
~/lib/emacs/lisp/calc-2.02f/calc-units
/usr/sww/pkg/emacs-24.2/share/emacs/24.2/lisp/calc/calc-undo hides 
~/lib/emacs/lisp/calc-2.02f/calc-undo
/usr/sww/pkg/emacs-24.2/share/emacs/24.2/lisp/calc/calc-trail hides 
~/lib/emacs/lisp/calc-2.02f/calc-trail
/usr/sww/pkg/emacs-24.2/share/emacs/24.2/lisp/calc/calc-stuff hides 
~/lib/emacs/lisp/calc-2.02f/calc-stuff
/usr/sww/pkg/emacs-24.2/share/emacs/24.2/lisp/calc/calc-store hides 
~/lib/emacs/lisp/calc-2.02f/calc-store
/usr/sww/pkg/emacs-24.2/share/emacs/24.2/lisp/calc/calc-stat hides 
~/lib/emacs/lisp/calc-2.02f/calc-stat
/usr/sww/pkg/emacs-24.2/share/emacs/24.2/lisp/calc/calc-sel hides 
~/lib/emacs/lisp/calc-2.02f/calc-sel
/usr/sww/pkg/emacs-24.2/share/emacs/24.2/lisp/calc/calc-rules hides 
~/lib/emacs/lisp/calc-2.02f/calc-rules
/usr/sww/pkg/emacs-24.2/share/emacs/24.2/lisp/calc/calc-rewr hides 
~/lib/emacs/lisp/calc-2.02f/calc-rewr
/usr/sww/pkg/emacs-24.2/share/emacs/24.2/lisp/calc/calc-prog hides 
~/lib/emacs/lisp/calc-2.02f/calc-prog
/usr/sww/pkg/emacs-24.2/share/emacs/24.2/lisp/calc/calc-poly hides 
~/lib/emacs/lisp/calc-2.02f/calc-poly
/usr/sww/pkg/emacs-24.2/share/emacs/24.2/lisp/calc/calc-mode hides 
~/lib/emacs/lisp/calc-2.02f/calc-mode
/usr/sww/pkg/emacs-24.2/share/emacs/24.2/lisp/calc/calc-misc hides 
~/lib/emacs/lisp/calc-2.02f/calc-misc
/usr/sww/pkg/emacs-24.2/share/emacs/24.2/lisp/calc/calc-math hides 
~/lib/emacs/lisp/calc-2.02f/calc-math
/usr/sww/pkg/emacs-24.2/share/emacs/24.2/lisp/calc/calc-map hides 
~/lib/emacs/lisp/calc-2.02f/calc-map
/usr/sww/pkg/emacs-24.2/share/emacs/24.2/lisp/calc/calc-macs hides 
~/lib/emacs/lisp/calc-2.02f/calc-macs
/usr/sww/pkg/emacs-24.2/share/emacs/24.2/lisp/calc/calc-lang hides 
~/lib/emacs/lisp/calc-2.02f/calc-lang
/usr/sww/pkg/emacs-24.2/share/emacs/24.2/lisp/calc/calc-keypd hides 
~/lib/emacs/lisp/calc-2.02f/calc-keypd
/usr/sww/pkg/emacs-24.2/share/emacs/24.2/lisp/calc/calc-incom hides 
~/lib/emacs/lisp/calc-2.02f/calc-incom
/usr/sww/pkg/emacs-24.2/share/emacs/24.2/lisp/calc/calc-help hides 
~/lib/emacs/lisp/calc-2.02f/calc-help
/usr/sww/pkg/emacs-24.2/share/emacs/24.2/lisp/calc/calc-graph hides 
~/lib/emacs/lisp/calc-2.02f/calc-graph
/usr/sww/pkg/emacs-24.2/share/emacs/24.2/lisp/calc/calc-funcs hides 
~/lib/emacs/lisp/calc-2.02f/calc-funcs
/usr/sww/pkg/emacs-24.2/share/emacs/24.2/lisp/calc/calc-frac hides 
~/lib/emacs/lisp/calc-2.02f/calc-frac
/usr/sww/pkg/emacs-24.2/share/emacs/24.2/lisp/calc/calc-fin hides 
~/lib/emacs/lisp/calc-2.02f/calc-fin
/usr/sww/pkg/emacs-24.2/share/emacs/24.2/lisp/calc/calc-forms hides 
~/lib/emacs/lisp/calc-2.02f/calc-forms
/usr/sww/pkg/emacs-24.2/share/emacs/24.2/lisp/calc/calc-cplx hides 
~/lib/emacs/lisp/calc-2.02f/calc-cplx
/usr/sww/pkg/emacs-24.2/share/emacs/24.2/lisp/calc/calc-comb hides 
~/lib/emacs/lisp/calc-2.02f/calc-comb
/usr/sww/pkg/emacs-24.2/share/emacs/24.2/lisp/calc/calc-bin hides 
~/lib/emacs/lisp/calc-2.02f/calc-bin
/usr/sww/pkg/emacs-24.2/share/emacs/24.2/lisp/calc/calc-embed hides 
~/lib/emacs/lisp/calc-2.02f/calc-embed
/usr/sww/pkg/emacs-24.2/share/emacs/24.2/lisp/calc/calc-alg hides 
~/lib/emacs/lisp/calc-2.02f/calc-alg
/usr/sww/pkg/emacs-24.2/share/emacs/24.2/lisp/calc/calc-arith hides 
~/lib/emacs/lisp/calc-2.02f/calc-arith
/usr/sww/pkg/emacs-24.2/share/emacs/24.2/lisp/calc/calc-ext hides 
~/lib/emacs/lisp/calc-2.02f/calc-ext

Features:
(shadow emacsbug two-column iso-transl arc-mode archive-mode tabulated-
list tramp-cache tramp-sh sort rect cus-edit cus-start cus-load doc-view
image-mode vc-svn dabbrev perl-mode skeleton sh-script executable novice
mh-limit flow-fill make-mode calc-menu calc calc-loaddefs calc-macs
latexenc jka-compr dired-aux vc ediff vc-dispatcher nroff-mode help-mode
view etags tabify man pcmpl-unix vc-git ispell misearch multi-isearch mh-
thread mh-search newcomment mh-alias crm mh-identity mh-letter mh-comp
sendmail network-stream starttls url-queue url-http url-auth url-gw url-
cache url url-proxy url-privacy url-expand url-methods url-history url-
cookie url-util url-parse url-vars mule-util shr-color color shr smiley
mail-extr mh-show gnus-cite mh-funcs mh-seq mh-inc hl-line mh-tool-bar
mh-xface mh-utils mh-folder which-func imenu mh-scan grep tramp tramp-
compat auth-source eieio byte-opt bytecomp byte-compile cconv macroexp
assoc advice help-fns advice-preload tramp-loaddefs cs61b server goto-
addr sgml-mode thingatpt browse-url shell pcomplete gjdb gud python-mode
info-look info java-mode-indent-annotations rst compile comint ansi-
color psvn derived edmacro kmacro log-edit ring pcvs-util add-log diff-
mode easy-mmode pp elp ediff-merg ediff-diff ediff-wind ediff-mult ediff-
help ediff-init ediff-util dired cc-mode cc-fonts cc-guess cc-menus cc-
cmds cc-styles cc-align cc-engine cc-vars cc-defs cpt my-mh qp gnus-art
mm-uu mml2015 epg-config gnus-sum nnoo gnus-group gnus-undo nnmail mail-
source gnus-start gnus-spec gnus-int gnus-range gnus-win gnus gnus-ems
nnheader wid-edit message format-spec rfc822 mail-utils gmm-utils
mailheader mh-mime mh-gnus mml easymenu mm-view mml-smime mml-sec smime
password-cache dig mm-decode mm-bodies mm-encode mail-parse rfc2231
rfc2047 rfc2045 ietf-drums mm-util mail-prsvr gnus-util mh-e regexp-opt
mh-compat mailabbrev mh-acros mh-buffers mh-loaddefs mailcap cl tls time-
date tooltip ediff-hook vc-hooks lisp-float-type mwheel x-win x-dnd tool-
bar dnd fontset image fringe lisp-mode register page menu-bar rfn-
eshadow timer select scroll-bar mouse jit-lock font-lock syntax facemenu
font-core frame cham georgian utf-8-lang misc-lang vietnamese tibetan
thai tai-viet lao korean japanese hebrew greek romanian slovak czech
european ethiopic indian cyrillic chinese case-table epa-hook jka-cmpr-
hook help simple abbrev minibuffer loaddefs button faces cus-face files
text-properties overlay sha1 md5 base64 format env code-pages mule
custom widget hashtable-print-readable backquote make-network-process
dynamic-setting x-toolkit x multi-tty emacs)