[elpa] externals/multishell 86e07ba8db 1/3: Refine multishell features description.

[ken manheimer]

branch: externals/multishell
commit 86e07ba8db36743ea2082bb1839a568b9cee254b
Author: Ken Manheimer <ken.manheimer@gmail.com>
Commit: Ken Manheimer <ken.manheimer@gmail.com>

    Refine multishell features description.
    
    In README.md and multishell.el commentary.
---
 README.md     | 62 ++++++++++++++++++++++++++++++++++-------------------------
 multishell.el | 47 ++++++++++++++++++++++++--------------------
 2 files changed, 62 insertions(+), 47 deletions(-)

diff --git a/README.md b/README.md
index 4004e51874..55d2991b39 100644
--- a/README.md
+++ b/README.md
@@ -1,49 +1,59 @@
 multishell.el
 =============
 
-Facilitate use of multiple local and remote Emacs shell buffers.
+Organize multiple local and remote Emacs shell buffers.
 
 Multishell is available via Emacs package manager, [in 
ELPA](https://elpa.gnu.org/packages/multishell.html). Install "multishell" from 
the `M-x package-list-packages` listing.
 
-I use the emacs shell a *lot*, including separate shells for separate
-project, and more shells for access to remote systems (which I do a lot, as
-a systems administrator). On top of emacs' powerful shell and tramp
-facilities, use a `multishell` (customization-activated) key binding to:
+I use almost as many emacs shell buffers as I do tabs in my browser
+sessions. Multishell makes it easy to organize my use of them with distinct
+names for each, tramp syntax for remote and / or sudo shells, a roster of
+them all that can be saved between emacs sessions (preserving remote and
+sudo specifications), and more. With a customizable master keybinding,
+multishell makes it easy to:
 
 * Get to the input point from wherever you are in a shell buffer,
-  ... or to any of your shell buffers, from anywhere inside emacs.
+  or to any of your shell buffers, from anywhere inside emacs.
 
-* Use universal arguments to launch and choose among alternate shell buffers,
-  ... and change which is the current default.
+* Use universal arguments and name completion to launch a new or choose
+  among existing shell buffers, and change which is the current default.
 
-* Easily restart disconnected shells, or shells from prior sessions
-  ... the latter from Emacs builtin savehist minibuf history persistence
+* Easily restart exited shells, or shells from prior emacs sessions.
 
-* Append a path to a new shell name to launch a shell in that directory,
-  ... and use a path with Emacs tramp syntax to launch a remote shell -
-  for example:
+* Specify an initial path for the shell. By using Emacs tramp syntax you
+  can launch a sudo and/or remote shell.
 
-  * `#root/sudo:root@localhost:/etc` for a buffer named "#root" with a
-    root shell starting in /etc.
+  For example, specifying the following at the multishell buffer name
+  prompt will:
 
-  * `/ssh:example.net:/` for a shell buffer in / on example.net.
-    The buffer will be named "*example.net*".
+  * `#root/sudo:root@localhost:/etc` launch a shell in a buffer named
+    "*#root*" with a root shell starting in /etc.
 
-  * `#ex/ssh:example.net|sudo:root@example.net:/etc` for a root shell
-    starting in /etc on example.net named "*#ex*".
+  * `/ssh:example.net:` launch a shell buffer in your homedir on
+    example.net.  The buffer will be named "*example.net*".
 
-  * `interior/ssh:gateway.corp.com|ssh:interior.corp.com:` to go via
-    gateway.corp.com to your homedir on interior.corp.com.  The buffer
-    will be named "*interior*". You could append a sudo hop, and so on.
+  * `#ex/ssh:example.net|sudo:root@example.net:/etc` launch a root
+    shell starting in /etc on example.net named "*#ex*".
 
-* Thanks to tramp, file visits from the shell will seamlessly be on the
-  host where the shell is running, in the auspices of the target account.
+  * `interior/ssh:gateway.corp.com|ssh:interior.corp.com:` via
+    gateway.corp.com launch a shell in your homedir on interior.corp.com.
+    The buffer will be named "*interior*". You could append a sudo hop,
+    and so on.
+
+* Thanks to tramp, file visits initiated in remote shell buffers will
+  seamlessly be on the hosts where the shells are running, in the auspices
+  of the account being used.
+
+* Manage your list of shells, current and past, as a collection.
+
+* Of course, emacs completion makes it easy to switch to an already
+  existing shell buffer, or one in your history roster, by name.
 
 See the `multishell-pop-to-shell` docstring (in
 [multishell.el](multishell.el)) for details, and
 [getting-to-a-shell.md](getting-to-a-shell.md) for the nitty-gritty
-decision tree that determines where the keybinding according to the various
-conditions.
+decision tree that determines where the keybinding goes according to the
+various conditions.
 
 Customize-group `multishell' to select and activate a keybinding and set
 various behaviors. Customize-group `savehist' to preserve buffer
diff --git a/multishell.el b/multishell.el
index 87afa27b7b..49c4fbea22 100644
--- a/multishell.el
+++ b/multishell.el
@@ -15,38 +15,43 @@
 ;; Fundamentally, multishell is the function `multishell-pop-to-shell' -
 ;; a la `pop-to-buffer' - plus a keybinding. Together, they enable you to:
 ;;
-;; * Get to the input point from wherever you are in a shell buffer,
-;;   ... or to any of your shell buffers, from anywhere inside emacs.
+;; * Easily get to the input point from wherever you are in a shell buffer,
+;;   or to any of your shell buffers, from anywhere inside emacs.
 ;;
-;; * Use universal arguments to launch and choose among alternate shell 
buffers,
-;;   ... and change which is the current default.
+;; * Use universal arguments and name completion to launch a new or choose
+;;   among existing shell buffers, and change which is the current default.
 ;;
-;; * Easily restart disconnected shells, or shells from prior sessions
-;;   ... the latter from Emacs builtin savehist minibuf history persistence
+;; * Easily restart exited shells, or shells from emacs prior sessions.
 ;;
-;; * Append a path to a new shell name to launch a shell in that directory,
-;;   ... and use a path with Emacs tramp syntax to launch a remote shell -
-;;   for example:
+;; * Specify an initial path for the shell. By using Emacs tramp syntax you
+;;   can launch a sudo and/or remote shell.
 ;;
-;;   * `#root/sudo:root@localhost:/etc` for a buffer named "*#root*" with a
-;;     root shell starting in /etc.
+;;   For example, specifying the following at the multishell buffer name
+;;   prompt will:
 ;;
-;;   * `/ssh:example.net:` for a shell buffer in your homedir on example.net.
-;;     The buffer will be named "*example.net*".
+;;   * `#root/sudo:root@localhost:/etc` launch a shell in a buffer named
+;;     "*#root*" with a root shell starting in /etc.
 ;;
-;;   * `#ex/ssh:example.net|sudo:root@example.net:/var/log` for a root shell
-;;     starting in /var/log on example.net named "*#ex*".
+;;   * `/ssh:example.net:` launch a shell buffer in your homedir on
+;;     example.net.  The buffer will be named "*example.net*".
 ;;
-;;   * 'interior/ssh:gateway.corp.com|ssh:interior.corp.com:' to go via
-;;     gateway.corp.com to your homedir on interior.corp.com.  The buffer
-;;     will be named "*interior*". You could append a sudo hop, and so on.
+;;   * `#ex/ssh:example.net|sudo:root@example.net:/etc` launch a root
+;;     shell starting in /etc on example.net named "*#ex*".
 ;;
-;; * Thanks to tramp, file visits from the shell will seamlessly be in
-;;   the auspices of the target account, and relative to the current
-;;   directory, on the host where the shell is running.
+;;   * `interior/ssh:gateway.corp.com|ssh:interior.corp.com:` via
+;;     gateway.corp.com launch a shell in your homedir on interior.corp.com.
+;;     The buffer will be named "*interior*". You could append a sudo hop,
+;;     and so on.
+;;
+;; * Thanks to tramp, file visits initiated in remote shell buffers will
+;;   seamlessly be on the hosts where the shells are running, in the auspices
+;;   of the account being used.
 ;;
 ;; * Manage your list of shells, current and past, as a collection.
 ;;
+;; * Of course, emacs completion makes it easy to switch to an already
+;;   existing shell buffer, or one in your history roster, by name.
+;;
 ;; See the `multishell-pop-to-shell' docstring for details.
 ;;
 ;; Customize-group `multishell' to select and activate a keybinding and set