Finish script and documentation

README.md

@@ -46,6 +46,10 @@ remain at the end of the file at all times for TPM to work properly!
 
 After adding a plugin, press **Ctrl+\<prefix> I** to install the plugins.
 
+Finally, you can run `sh ~./config/tmux/scripts/install.sh`. This will create a
+symbolic link to the `hxi`-Script in your local `bin` folder. `~/.local/bin`.
+Make sure the folder is in your `$PATH` variable.
+
 ## Basic usage
 
 Independent from the layout you use, the basic usage is standard tmux operation.
@@ -79,13 +83,73 @@ tests (in order) for the following build-systems:
 The process will open a popup window, in which the build is performed. After the
 build stops, the window will stay open until a key is pressed.
 
-## Launch different editor layouts
+## Launch different IDE layouts
 
-The configuration comes with a script named `hxi`, which is installed into the
-` ~/.local/bin` folder. When the script is started, it launches a new tmux
-session with a randomised name. In this session, an editor is opened, with the
-given parameters. Then the script looks for a file named `.tmux.layout`, which
-needs to be an executeable script file. It then sources the file. and finally
-attaches to the session, that was created. The sourced `.tmux.layout` file can
-be used to create an individual layout for the project folder you're in,
-creating new windows and panes, as needed.
+The main point of this tmux installation is to use tmux as an IDE-replacement.
+This means, it's central element is an editor, in our case the
+[helix](https://helix-editor.com) editor. To call tmux and open an editor, use
+the `hxi` command. This command will open an instance of helix inside a unique
+tmux session. This allows you to have several instances open at the same time,
+each in a separate session. The editor that is used, can be your favourite
+editor, as it is taken from the `$EDITOR` variable. But we assume here, it's
+helix.
+
+When calling `hxi` a tmux session will be opened, with your editor in the only
+window and pane that is opened. However, depending on your environment, you
+might want to organize some other panes on your window as well. The trouble is:
+They may differ, depending on the project, your working on. Maybe you'll need a
+simple terminal, maybe you'll need an ssh connection to a remote computer, or a
+monitoring tool. In order to provide this on an as-needed-basis, you can place a
+file named `./layout.tmux` inside your project folder. Whenever you launch
+`hxi`, the script will look for a file of that name, and execute it. The file
+will be executed after the tmux-session is created and the editor opened, but
+before the scriopt connects to the session. It's main purpose is to use the
+`tmux` command to reconfigure the environment, but it can be used to perform any
+action you want to be executed before the session starts. It's only parameter is
+the sessionid, that is passed from `hxi`. Every `tmux`-command needs to pass
+this on, to make sure the correct session is configured.
+
+As an example, let's assume, you want to work on your PIDP-10 Assembler project.
+To do this, you'd like the editor to open, and have two panes below: One showing
+the PDP 10's system console, and the other giving you a command line on the
+Raspberry Pi in order to be able to copy data between the Pi and the simulated
+PDP 10. The following `.layout.tmux` file allows for this.
+
+```bash
+#!/usr/bin/zsh
+# Create a layout for development on the PDP-10
+RPDP=$(where rpdp)
+
+# Split the window at the bottom and open a
+$MUX split-window -v -l 8 -t ${SESSIONID}:0 telnet pidp10.local 1025
+
+# Split again, and connect via ssh to the host machine
+$MUX split-window -h -t ${SESSIONID}:0 ssh pidp10.local
+
+# Finally, start an instance of the Knight-TV console
+if [[ -v RPDP ]]; then
+  $RPDP tvcon
+fi
+```
+
+There are two variables, that the script inherits from `hxi`: `$SESSIONID`
+contains the id of the current tmux session. The `$MUX` variable contains the
+path to the tmux-command itself. If you use the tmux-command, always pass
+`-t $SESSIONID` to it, so the command gets executed on the correct session.
+
+In the line
+
+```bash
+$MUX split-window -v -l 8 -t ${SESSIONID}:0 telnet pidp10.local 1025
+```
+
+the editor window is split vertially, so the new pane is 8 lines high below the
+edior. The split window contains a call to the telnet connection of the PDP 10,
+that connects to the system console.
+
+The next line splits the new pane again, this time horizontally, and create a
+thrird pane, with an SSH-session to the PDP 10's host system.
+
+The final lines are an example of calling an external service from the start
+script: It will check if the `rpdp` tool is installed, and -if so- run the
+Knight-TV-Terminal emulatior, which will open in a separate window.

scripts/hxi

@@ -1,25 +1,26 @@
 #!/usr/bin/zsh
 # Runs the IDE
 
+PARAMS=$@
 SESSIONID="IDE-${RANDOM}"
-TMUX=$(where tmux)
+MUX=$(where tmux)
 
 # Set editor to helix, if unset
-if [ -z ${EDITOR+x} ]; then
+if [[ -v EDITOR ]]; then
   EDITOR=$(where hx)
 fi
 
 # Open a new session with a random name
-$TMUX new-session -d -s $SESSINID $EDITOR
-$TMUX rename-window -t ${SESSIONID}:0 "TMUX IDE"
+$MUX new-session -d -s $SESSIONID -x "$(tput cols)" -y "$(tput lines)" $EDITOR $PARAMS 
+$MUX rename-window -t ${SESSIONID}:0 "TMUX IDE"
 
 # check, if a layout file is present, and run it.
-if [ -f ./.tmux.layout ]; then
-  source ./.tmux.layout
+if [ -f ./.layout.tmux ]; then
+  source ./.layout.tmux
 fi
 
 # Finally, select the editor window in the current session,
 # and attach to the session
-$TMUX select-window -t ${SESSIONID}:0
-$TMUX select-pane -t 0
-$TMUX attach-session -t ${SESSIONID}
+$MUX select-window -t ${SESSIONID}:0
+$MUX select-pane -t 0
+$MUX attach-session -t ${SESSIONID}

scripts/install.sh

@@ -1,3 +1,3 @@
 #!/bin/sh
 mkdir -p ~/.local/bin
-cp ~/.config/tmux/scripts/hxi ~/.local/bin
+ln -s ~/.config/tmux/scripts/hxi ~/.local/bin/hxi