Subject: Re: bug#54227: 29.0.50; [PATCH] Inconsistencies with Eshell variable interpolation

From: Eli Zaretskii <[email-masked]>
Date: Thu, 03 Mar 2022 18:57:07 +0200

> From: Jim Porter <[email-masked]>
> Date: Wed, 2 Mar 2022 22:35:22 -0800
> 
> +@item $@var{expr}[@var{i...}]
> +Expands to the @var{i}th element of the result of @var{expr}, an
> +expression in one of the above forms listed here.  If multiple indices
> +are supplied, this will return a list containing the elements for each
> +index.  If @var{expr}'s value is a string, it will first be split at
> +whitespace to make it a list.  If @var{expr}'s value is an alist
> +(@pxref{Association List Type, Association Lists, , elisp, The Emacs
> +Lisp Reference Manual}), this will call @code{assoc} on the result of
> +@var{expr}, returning the @code{cdr} of the element of the result
> +whose car is equal to @code{"i"}.

Thanks.

I think the documentation parts of this should be reworded to be
consistent with the manual's audience.  The Eshell manual is for
users, not necessarily for Lisp programmers.  So explaining features
in terms of Emacs primitives, such as assoc and car/cdr/caar is not
the best way of documenting them.

Can we reword this text such that the way the feature works is clear
to non-programmers as well?