behaviour of shell-command-on-region

[Dan Davison]

I'm having trouble understanding the output-buffer and replace arguments
to shell-command-on-region:

The argument list and docstring are reproduced below.

If I put point on the last parenthesis and do C-x C-e I was expecting
this to insert the date after point. However, it erases the current
buffer and inserts the date:

(shell-command-on-region (point-min) (point-max) "date" 'current-buffer)

It's seeming to me that the docstring and behaviour don't match. Where
am I going wrong?

Dan

emacs-version 23.1.1 ubuntu 9.10


The argument list for shell-command-on-region is:

(shell-command-on-region start end command &optional output-buffer
replace error-buffer display-error-buffer)

The docstring says:

    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.