From: Ken Manheimer <ken.manheimer@gmail.com>
Date: Sun, 24 Jan 2016 20:34:27 +0000 (-0500)
Subject: multishell - describe shell choice decision tree in getting-to-a-shell.md
X-Git-Url: https://code.delx.au/gnu-emacs-elpa/commitdiff_plain/07d8d96720708e9923c1117da07a93e34163769e

multishell - describe shell choice decision tree in getting-to-a-shell.md
---

diff --git a/getting-to-a-shell.md b/getting-to-a-shell.md
new file mode 100644
index 000000000..a2ad6493d
--- /dev/null
+++ b/getting-to-a-shell.md
@@ -0,0 +1,41 @@
+Multishell enables you to get to the input prompt in the shell you want
+with as few keystrokes as possible.
+
+* One keybinding, unmodified, gets you to the your current default shell, if
+  not in a shell, or to the input prompt of the current shell, if you're in
+  one.
+
+* Use the universal argument to select a specific shell buffer, wherever
+  point happens to be residing. Enter an empty line to the prompt to go to
+  your current default shell, or use completing read to go to a shell from
+  your multishell history, or start a new shell at the path you specify -
+  including remote paths, using tramp syntax. (See the
+  multishell-pop-to-shell docstring in [multishell.el](multishell.el) for
+  details.)
+
+* Use a doubled universal argument to set the shell you choose to be the
+  current default. (The prompt will indicate that mode with a "<==".)
+
+Here's the decision tree:
+
+* No universal argument - use:
+
+  * From-buffer is shell buffer: use from-buffer current name/path
+    - if shell/connection is stopped, restart/reconnect
+    - if not at input prompt, go there
+  * From-buffer is not shell buffer: 
+    - Go to multishell-primary-name current name/path, creating or
+      restarting and/or reconnecting if that shell is not currently running.
+
+* Universal argument provided - use:
+
+  - No name is specified - use current multishell-primary-name path
+  * Name is specified - use named buffer (creating if not already present):
+    * Path is also specified:
+      - shell is running - ignore new path
+      - shell will be started or restarted - use new path
+    * No path is specified:
+      - Name has history: use path from history
+      - Name has no history: use path that target buffer already has or inherits
+    - If the universal argument is doubled, set the selected shell as the
+      default one, going forwards.