From ec52b44f694f2515bb3673f998e6ea80d2d31e08 Mon Sep 17 00:00:00 2001
From: Jim Porter <jporterbugs@gmail.com>
Date: Sun, 27 Feb 2022 13:20:51 -0800
Subject: [PATCH 1/2] 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 261e88d00c..88a7d7b130 100644
--- a/doc/misc/eshell.texi
+++ b/doc/misc/eshell.texi
@@ -1016,6 +1016,12 @@ Dollars Expansion
 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
@@ -1030,6 +1036,11 @@ Dollars Expansion
 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 5c8dacd980..cfefe15c9c 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,
@@ -423,9 +429,12 @@ eshell-parse-variable-ref
 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.25.1