From 2c3d1b6bf41509bf0ba8995925fec9f20d8ed89d Mon Sep 17 00:00:00 2001
From: Jim Porter <jporterbugs@gmail.com>
Date: Sun, 27 Feb 2022 13:20:51 -0800
Subject: [PATCH] Improve/correct documentation about Eshell variable expansion

* lisp/eshell/esh-var.el: Correct documentation comment.
(eshell-parse-variable-ref): Correct docstring.

* doc/misc/eshell.texi (Dollars Expansion): Add documentation for
$"var"/$'var' and $<command> syntaxes.
---
 doc/misc/eshell.texi   | 11 +++++++++++
 lisp/eshell/esh-var.el | 15 ++++++++++++---
 2 files changed, 23 insertions(+), 3 deletions(-)

diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi
index 4f1d8c15da3..662c96dc920 100644
--- a/doc/misc/eshell.texi
+++ b/doc/misc/eshell.texi
@@ -583,6 +583,12 @@ of familiarity.
 Expands to the value bound to @code{var}.  This is the main way to use
 variables in command invocations.
 
+@item $"var"
+@item $'var'
+Expands to the value bound to @code{var}.  This is useful to
+disambiguate the variable name when concatenating it with another
+value, such as @samp{$"var"-suffix}.
+
 @item $#var
 Expands to the length of the value bound to @code{var}.  Raises an error
 if the value is not a sequence
@@ -597,6 +603,11 @@ it can be used in a string, such as @samp{/some/path/$(lisp).txt}.
 Returns the output of @command{command}, which can be any valid Eshell
 command invocation, and may even contain expansions.
 
+@item $<command>
+As with @samp{$@{command@}}, evaluates the Eshell command invocation
+@command{command}, but writes the output to a temporary file and
+returns the file name.
+
 @item $var[i]
 Expands to the @code{i}th element of the value bound to @code{var}.  If
 the value is a string, it will be split at whitespace to make it a list.
diff --git a/lisp/eshell/esh-var.el b/lisp/eshell/esh-var.el
index 081938b4e4a..1d5d85debad 100644
--- a/lisp/eshell/esh-var.el
+++ b/lisp/eshell/esh-var.el
@@ -34,7 +34,8 @@
 ;;
 ;; "-" is a valid part of a variable name.
 ;;
-;;   $<MYVAR>-TOO
+;;   $\"MYVAR\"-TOO
+;;   $'MYVAR'-TOO
 ;;
 ;; Only "MYVAR" is part of the variable name in this case.
 ;;
@@ -55,6 +56,11 @@
 ;; Returns the value of an eshell subcommand.  See the note above
 ;; regarding Lisp evaluations.
 ;;
+;;   $<command>
+;;
+;; Evaluates an eshell subcommand, redirecting the output to a
+;; temporary file, and returning the file name.
+;;
 ;;   $ANYVAR[10]
 ;;
 ;; Return the 10th element of ANYVAR.  If ANYVAR's value is a string,
@@ -426,9 +432,12 @@ variable.
 Possible options are:
 
   NAME          an environment or Lisp variable value
-  <LONG-NAME>   disambiguates the length of the name
+  \"LONG-NAME\"   disambiguates the length of the name
+  'LONG-NAME'   as above
   {COMMAND}     result of command is variable's value
-  (LISP-FORM)   result of Lisp form is variable's value"
+  (LISP-FORM)   result of Lisp form is variable's value
+  <COMMAND>     write the output of command to a temporary file;
+                result is the file name"
   (cond
    ((eq (char-after) ?{)
     (let ((end (eshell-find-delimiter ?\{ ?\})))
-- 
2.39.2