complete SHELL doc: keybinding and tmux usage

doc/docs/shell_cmdline.md

@@ -8,33 +8,38 @@ provided to easily and interactively execute BLISS *commands* and
 
 Use `-h` flag to get help about bliss command line interface:
 
-        % bliss -h
-        Usage: bliss [-l | --log-level=<log_level>] [-s <name> | --session=<name>] [--no-tmux]
-               bliss [-v | --version]
-               bliss [-c <name> | --create=<name>]
-               bliss [-d <name> | --delete=<name>]
-               bliss [-h | --help]
-               bliss --show-sessions
-               bliss --show-sessions-only
-        
-        Options:
-            -l, --log-level=<log_level>   Log level [default: WARN] (CRITICAL ERROR INFO DEBUG NOTSET)
-            -s, --session=<session_name>  Start with the specified session
-            -v, --version                 Show version and exit
-            -c, --create=<session_name>   Create a new session with the given name
-            -d, --delete=<session_name>   Delete the given session
-            -h, --help                    Show help screen and exit
-            --no-tmux                     Deactivate Tmux usage
-            --show-sessions               Display available sessions and tree of sub-sessions
-            --show-sessions-only          Display available sessions names only
-
+```
+% bliss -h
+Usage: bliss [-l | --log-level=<log_level>] [-s <name> | --session=<name>]
+             [--no-tmux]
+       bliss [-v | --version]
+       bliss [-c <name> | --create=<name>]
+       bliss [-d <name> | --delete=<name>]
+       bliss [-h | --help]
+       bliss --show-sessions
+       bliss --show-sessions-only
+
+Options:
+    -l, --log-level=<log_level>   Log level [default: WARN]
+                                  {CRITICAL; ERROR; INFO; DEBUG; NOTSET}
+    -s, --session=<session_name>  Start with the specified session
+    -v, --version                 Show version and exit
+    -c, --create=<session_name>   Create a new session with the given name
+    -d, --delete=<session_name>   Delete the given session
+    -h, --help                    Show help screen and exit
+    --no-tmux                     Deactivate Tmux usage
+    --show-sessions               Display sessions and tree of sub-sessions
+    --show-sessions-only          Display sessions names only
+```
 
 ### Version
 
 Use `-v` or `--version` option to get the current version of a BLISS installation:
 
-    % bliss --version
-    BLISS version 0.2
+```
+% bliss --version
+BLISS version 0.2
+```
 
 ### Logging level
 
@@ -43,37 +48,44 @@ Use `-v` or `--version` option to get the current version of a BLISS installatio
 ### Sessions
 Use `-s` to start an existing session:
 
-    % bliss -s test_session
-                       __         __   __
-                      |__) |   | /__` /__`
-                      |__) |__ | .__/ .__/
+```
+% bliss -s test_session
+                   __         __   __
+                  |__) |   | /__` /__`
+                  |__) |__ | .__/ .__/
 
 
-    Welcome to BLISS version 1e7eb5c2 running on PCGUILLOU (in bliss_env Conda environment)
-    Copyright (c) ESRF, 2015-2018
+Welcome to BLISS version erbs5c2 running on PCGUILLOU
+                                         in bliss_env Conda environment
+Copyright (c) ESRF, 2015-2019
+```
 
 Use `--show-sessions` option to get the list of available sessions:
 
-     % bliss --show-sessions
-     Available BLISS sessions are:
-       flint
-       lima_test_session
-       test_session
+```
+% bliss --show-sessions
+Available BLISS sessions are:
+  flint
+  lima_test_session
+  test_session
+```
 
 Other commands are also displaying the available sessions:
 
      % bliss --show-sessions-only
 
-#### Automatic creation of a new session
+#### Creation of a new session
 
 Use `--create` or `-c` to create the skeleton of a new session:
 
-    bliss -c eh1
-    % bliss -c eh1
-    creating 'eh1' session
-    Creating: /bliss/users/guilloud/local/beamline_configuration/sessions/eh1_setup.py
-    Creating: /bliss/users/guilloud/local/beamline_configuration/sessions/eh1.yml
-    Creating: /bliss/users/guilloud/local/beamline_configuration/sessions/scripts/eh1.py
+```
+bliss -c eh1
+% bliss -c eh1
+creating 'eh1' session
+Creating: /.../local/beamline_configuration/sessions/eh1_setup.py
+Creating: /.../local/beamline_configuration/sessions/eh1.yml
+Creating: /.../local/beamline_configuration/sessions/scripts/eh1.py
+```
 
 #### Removing an existing session
 
@@ -83,14 +95,32 @@ Use `--create` or `-c` to create the skeleton of a new session:
 * setup file
 * default session script (see above)
 
+
+## Multiple panels (Tmux)
+
+The BLISS shell uses *Tmux* to handle multiple **panels**:
+
+* The default one is the *"Bliss shell panel"* used to enter user
+  commands and to display majority of answers to commands.
+* The *Scan panel* is used to display output of scans. It is
+  automaticaly displayed when a scan starts.
+
+This behaviour has been introduced in order to avoid the used to be
+flooded by scan outputs.
+
+The `F5` key is used to switch between thoses two panels.
+
+
 #### Deactivating Tmux (terminal multiplexer) usage
 
 Use `--no-tmux` to start a Bliss session without the Tmux terminal
-multiplexer.  In a Bliss session without Tmux, the scans output won't
+multiplexer. In a Bliss session without Tmux, the scans output won't
 be printed in a separated window and will be shown in the main command
 line window.
 
-    % bliss -s test_session --no-tmux
+```
+% bliss -s test_session --no-tmux
+```
 
 
 ### Mouse and Key bindings in Tmux
@@ -102,14 +132,14 @@ line window.
 * `MouseButtonRight`:
     * exit copy-mode
 
-* `up`: go one *line* up in history (line per line if multi-line command)
-* `down`: go one *line* down in history (line per line if multi-line command)
-* `Ctrl-Left`: jump to begining of (previous) word
-* `Ctrl-Right`: jump to end of (next) word
+* `Up` or `Ctrl-p`: go one *line* up in history (line per line if multi-line command)
+* `Down` or `Ctrl-n`: go one *line* down in history (line per line if multi-line command)
+* `Ctrl-Left` or `Alt-b`: jump to begining of (previous) word
+* `Ctrl-Right` or `Alt-f`: jump to end of (next) word
 * `PageUp`: go one *command* up in history (group of lines if multi-line command)
 * `PageDown`: go one *command* down in history (group of lines if multi-line command)
-* `Home`: go to begining of the current line
-* `End`: go to end of the current line
+* `Ctrl-a` or `Home`: go to begining of the current line
+* `Ctrl-e` or `End`: go to end of the current line
 * `Shift-PageUp`: Scroll up terminal buffer by half a page
 * `Shift-PageDown`: Scroll down terminal buffer by half a page
 * `Shift-Up`: Scroll up terminal buffer by one line
@@ -119,8 +149,28 @@ line window.
 
 * `Ctrl-s`: search in current command
 
-TODO:
-
-* `Ctrl-a`: go to begining of the current line
-* `Ctrl-e`: go to end of the current line
+* Cutting and Pasting:
+    * `Ctrl-w`: Cut the word before the cursor, adding it to the clipboard.
+    * `Ctrl-k`: (emacs mode) Cut the part of the line after the
+      cursor, adding it to the clipboard.
+    * `Ctrl-u`: Cut the part of the line before the cursor, adding it to the clipboard.
+    * `Ctrl-y`: (emacs mode) Paste the last thing you cut from the
+      clipboard. The `y` here stands for “yank”.
+
+* `Ctrl-Shift-_`: Undo your last key press. You can repeat this to undo multiple times.
+
+
+* Function keys:
+    * `F1`: ?
+    * `F2`: *ptpython* Menu
+    * `F3`: history mode:
+        * BLISS shell is hidden
+        * terminal is split into two new panels: *history* and *temporary buffer*
+        * navigation in history is done with usual keys (`arrows` of `Ctrl-<key>`)
+        * hitting `Space` copy the current history line into temporary buffer
+        * hitting `Enter` switches back to BLISS shell with temporary buffer pasted
+    * `F4`: switches `emacs` / `vi` mode (but why the hell to use vi ?)
+    * `F5`: switches between *BLISS commands shell* and *scan display panel*
+    * `F6`: switches to *paste mode* to paste code from external
+      application forcing no automatic indentation.