Review, refine

doc.zih.tu-dresden.de/docs/software/utilities.md

@@ -6,83 +6,70 @@ This pages provides tools and utilities that make your life on ZIH systems more
 
 ### Best Practices
 
-Terminal emulators are particularly well-suited for aiding the computer scientist in their trade. We generally favor TMUX("**T**erminal **Mu**litple**x**er") as it's newer than certain others and allows for better customization.
+Terminal multiplexers are particularly well-suited for aiding you as a computer scientist in your
+daily trade. We generally favor *tmux* as it's newer than certain others and allows for better
+customization.
 
-As there is already plenty of documentation on how to use Tmux,
-we won't repeat that here.
-But instead we would like to point you to those documentations:
+As there is already plenty of documentation on how to use tmux, we won't repeat that here. But
+instead we would like to point you to those documentations:
 
-* [Tmux manpage](https://manpages.org/tmux)
-* [Tmux.conf customization](https://tmuxguide.readthedocs.io/en/latest/tmux/tmux.html#tmux-conf)
-* [Tao of Tmux](https://tao-of-tmux.readthedocs.io/en/latest/)
-* [Tmux Cheat Sheet](https://tmuxcheatsheet.com/)
+* [tmux manpage](https://manpages.org/tmux)
+* [tmux.conf customization](https://tmuxguide.readthedocs.io/en/latest/tmux/tmux.html#tmux-conf)
+* [Tao of tmux](https://tao-of-tmux.readthedocs.io/en/latest/)
+* [tmux Cheat Sheet](https://tmuxcheatsheet.com/)
 
-### Making your interactive sessions more stable
+### Basic Usage
 
-Sometimes when you work on Taurus, you might encounter a connection loss.
-While working on fixing the underlying issue
-(e.g. an unstable Wi-Fi connection is certainly a good cause),
-you might however find it to be quite efficient,
-to just open up a Tmux session on Taurus,
-into which you can connect to the running sessions anytime again
-(e.g. also two days later):
+Tmux is a terminal multiplexer. It lets you switch easily between several programs in one
+terminal, detach them (they keep running in the background) and reattach them to a different
+terminal.
+
+The huge advantage is, that as long as your tmux session is running, you can connect to it and your
+settings (e.g., loaded modules, current working directory, ...) are in place. This is clearly
+beneficial when working within an unstable network with connection loses (e.g., traveling with the
+train in Germany), but also speed ups your workflow in the daily routine.
 
 ``` bash
 marie@compute$ tmux new-session -s marie_is_testing -d
 marie@compute$ tmux attach -t marie_is_testing
   echo "hello world"
   ls -l
-Ctrl+B & d
+Ctrl+b & d
 ```
 
-!!! note NOTE: Do note that if you want to jump out of your Tmux session,
-you would usually be using the key combination
-Control Key and B-Key (thus now addressing Tmux itself)
-and then you'd be using the D-Key to tell it to "detach" yourself from it
-(the Tmux session will stay alive and running).
-You can jump into it any time later by just using the aforementioned "tmux attach" command again.
-++ctrl+B++  ++D++
-
-### Using a more recent Tmux version on Taurus
+!!! note
 
-You might find yourself wanting to use a more recent Tmux version
-and you can do so with this command:
-``` bash
-marie@compute$ module load tmux
-```
+    If you want to jump out of your tmux session, hold the Control key and press 'b'. After that,
+    release both keys and type 'd'. With the first key combination you address tmux itself, whereas
+    'd' is the tmux command to "detach" yourself from it. The tmux session will stay alive and
+    running. You can jump into it any time later by just using the aforementioned "tmux attach"
+    command again.
 
-### Using Tmux on Computation Nodes
+### Using a More Recent Version
 
-At times it might be quite handy to have Tmux sessions running inside your computation jobs,
-such that you perform your computations within an interactive Tmux session.
-For this purpose the following shorthand is to be placed inside an sbatch file that comes in handy:
+More recent versions of tmux are available via the module system. Using the well know
+[module commands](modules.md#module-commands), you can query all available versions, load and unload
+certain versions from your environment, e.g.,
 
 ``` bash
-module load tmux/3.2a
-tmux new-session -s marie_is_computing -d
-sleep 1;
-tmux wait-for CHANNEL_NAME_MARIE
-```
-
-You can then connect to it like this:
-
-``` bash
-ssh -t "$(squeue -u $USER -o "%N" 2>/dev/null | tail -n 1)" "source /etc/profile.d/10_modules.sh; module load tmux/3.2a; tmux attach"
+marie@login$ module load tmux/3.2a
 ```
 
-### Error: Protocol version mismatch
+### Error: Protocol Version Mismatch
 
-When trying to connect to Tmux, you might encounter the following error message:
+When trying to connect to tmux, you might encounter the following error message:
 
 ``` bash
 marie@compute$ tmux a -t juhu
 protocol version mismatch (client 7, server 8)
 ```
 
-To solve this issue, make sure that the Tmux-version you invoke
-is the same as the Tmux-server that is running.
+To solve this issue, make sure that the tmux version you invoke
+is the same as the tmux server that is running.
 In particular you can determine your client's version with the command `tmux -V`.
-Try to load the appropriate tmux-version to match with your client’s tmux-server like this:
+Try to [load the appropriate tmux version](#using-a-more-recent-tmux-version) to match with your
+client's tmux server like this:
+
 ```
 marie@compute$ tmux -V
 tmux 1.8
@@ -92,17 +79,37 @@ marie@compute$ tmux -V
 tmux 3.2a
 ```
 
-!!! hint NOTE: When your client’s version is newer than the server-version,
-the aforementioned approach won't help you.
-In that case you might want to invoke `module unload tmux`,
-to downgrade your Tmux version to the Tmux version that is supplied with the operating system
-(which should have a lower version number).
+!!! hint
 
+    When your client's version is newer than the server version, the aforementioned approach
+    won't help you. In that case, you need to unload the loaded tmux module in order to downgrade
+    the client to the client version that is supplied with the operating system (which
+    should have a lower version number).
+
+### Using Tmux on Compute Nodes
+
+At times it might be quite handy to have tmux sessions running inside your computation jobs,
+such that you perform your computations within an interactive tmux session.
+For this purpose the following shorthand is to be placed inside the
+[jobfile](../jobs_and_resources/slurm.md#job-files):
+
+```bash
+module load tmux/3.2a
+tmux new-session -s marie_is_computing -d
+sleep 1;
+tmux wait-for CHANNEL_NAME_MARIE
+```
+
+You can then connect to the tmux session like this:
+
+``` bash
+ssh -t "$(squeue --me --noheader --format="%N" 2>/dev/null | tail -n 1)" "source /etc/profile.d/10_modules.sh; module load tmux/3.2a; tmux attach"
+```
 
-### My Tmux session is gone, what happened?
+### Where Is My Tmux Session?
 
-Please note that, as there are thousands of compute-nodes available,
-there are also multiple login nodes.
+Please note that, as there are thousands of compute nodes available, there are also multiple login
+nodes.
 
 Thus, try checking the other login nodes as well: