bug#2398: 23.0.90; MUSTMATCH read-file-name arg, confirm-nonexistent-file-or-buffer

1. Doc string of `read-file-name' says:
 
 "Fourth arg MUSTMATCH non-nil means require existing file's name.
  Non-nil and non-t means also require confirmation after completion."
 
A value such as `confirm-after-completion' does NOT mean that an
existing file name is required, AFAICT, so the first sentence is
false. Passing a value such as `confirm-after-completion' is no
guarantee that the string returned by `read-file-name' names an
existing file.
 
2. Similarly, the Elisp manual seems incorrect. You are not REQUIRED to
enter the name of an existing file, if MUSTMATCH is, say,
`confirm-after-completion'.  Completion is still lax in this case;
it's just that you must confirm that you want a non-existing file
name.
 
3. Beyond the fact that the doc is inaccurate (and confusing) on this
matter, the new behavior also breaks existing code. Any code that
passed a non-nil non-t value in order to guarantee that the value
returned by the function names an existing file is now broken.
 
4. The user option `confirm-nonexistent-file-or-buffer' is not even
documented in this regard in the Elisp manual.
 
5. The default value of `confirm-nonexistent-file-or-buffer' is
`after-completion', but if you do M-x customize-option
confirm-nonexistent-file-or-buffer you see "Always", not "After
completion", as the current value, and State says STANDARD. Something
is amiss here. Further, you can change the value, using the Value
Menu, to "Always" or to "After completion", but the actual value
remains the same: `after-completion'. This is a mess (bugged), and
quite confusing. And the available values don't seem to
correspond to either the documented completion behavior (see above) or
the actual completion behavior.
 
 
 
In GNU Emacs 23.0.90.1 (i386-mingw-nt5.1.2600)
 of 2009-02-01 on SOFT-MJASON
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (3.4)'