bug#67438: 29.1; WDired uses `substitute-in-file-name', so `$$' is changed to `$' - undocumented?

[Eli Zaretskii]

> From: Drew Adams <drew.adams@oracle.com>
> Date: Fri, 24 Nov 2023 23:35:54 +0000
> 
> emacs -Q
> 
> C-x d aaa   ; Go to a directory with a file named `aaa'
> 
> C-x C-q
> 
> Append $$$$ to the file name, to give `aaa$$$$'
> 
> C-x C-q
> 
> The resulting file was named `aaa$$', not `aaa$$$$'.
> 
> It seems that every occurrence of `$$' in a file name is treated as just
> `$'.  (The position of the `$$' in the new file name seems to be
> irrelevant.)
> 
> I see this in older Emacs releases as well.  I found nothing in the doc
> that would indicate that this is supposed to happen (and preferably
> why).  And the only occurrence of char `$' in wdired.el seems benign.
> 
> Ah, I found it - it comes from `substitute-in-file-name':
> 
>   (substitute-in-file-name "aa$$$$") ; -> "aa$$"
> 
> But is that appropriate behavior in this context?

The $ processing is an integral part of the Emacs interpretation of
file names.  The Emacs user manual says in "File Names":

     The character ‘$’ is used to substitute an environment variable into
  a file name.  The name of the environment variable consists of all the
  alphanumeric characters after the ‘$’; alternatively, it can be enclosed
  in braces after the ‘$’.  For example, if you have used the shell
  command ‘export FOO=rms/hacks’ to set up an environment variable named
  ‘FOO’, then both ‘/u/$FOO/test.c’ and ‘/u/${FOO}/test.c’ are
  abbreviations for ‘/u/rms/hacks/test.c’.  If the environment variable is
  not defined, no substitution occurs, so that the character ‘$’ stands
  for itself.  Note that environment variables set outside Emacs affect
  Emacs only if they are applied before Emacs is started.

     To access a file with ‘$’ in its name, if the ‘$’ causes expansion,
  type ‘$$’.  This pair is converted to a single ‘$’ at the same time that
  variable substitution is performed for a single ‘$’.  Alternatively,
  quote the whole file name with ‘/:’ (*note Quoted File Names::).  File
  names which begin with a literal ‘~’ should also be quoted with ‘/:’.

You will see this behavior _everywhere_ where Emacs accepts file names
from the user.  For example, try:

  M-x rename-file RET foo RET foo$$$$ RET

the resulting file name will be "foo$$", with 2 $ characters instead
of 4.

WDired interprets file names in the same way, and that is OK because
anything else would be inconsistent.

> If it is, then maybe the doc should tell you what to do if you want
> literal `$' chars.

It's hard to find where and how to document that in WDired's doc
string, without also describing the other special processing of file
names.

Again, this is part of the basic file-name semantics in Emacs, so
repeating it in every command that accepts file names would be
excessive and unjustified.