bug#54190: 29.0.50; [PATCH] Incorrect/missing documentation for some Eshell "$" syntaxes

[Jim Porter]

In the documentation for lisp/eshell/esh-var.el (and 
`eshell-parse-variable-ref' in that file), it says that "$<FOO>" is a 
way of accessing the value of the variable FOO to disambiguate the 
length of the variable name, sort of like "${FOO}" in ordinary shells. 
However, that's not actually true. The correct syntax for that is:

  $"FOO"
  ;; or...
  $'FOO'

In fact, what "$<FOO>" does is to run FOO as a subcommand, writing its 
stdout to a temp file, and returning that file's name. This is (very!) 
subtly implied in the Eshell manual in the "Bugs and ideas" section, 
where it says:

  `grep python $<rpm -qa>' doesn't work, but using `*grep' does

  This happens because the `grep' Lisp function returns immediately,
  and then the asynchronous `grep' process expects to examine the
  temporary file, which has since been deleted.

Attached is a patch which updates the documentation to correctly 
describe the current behavior. Note: since this is just a documentation 
change, it might be worth pushing to the 28 branch.

0001-Improve-correct-documentation-about-Eshell-variable-.patch
Description: Text document