Merge branch 'ws_restore_allocate' into 'preview'

Improve subsections on expiration and restoring workspaces

See merge request !1150

doc.zih.tu-dresden.de/docs/data_lifecycle/workspaces.md

@@ -324,7 +324,12 @@ ws_send_ical --filesystem horse --mail <your.email>@tu-dresden.de --workspace te
 
 ### Deletion of a Workspace
 
-To delete a workspace use the `ws_release` command. It is mandatory to specify the name of the
+There is an [Expire process](#expire-process) for every workspace filesystem running on a daily
+basis. These processes check the lifetime of all workspaces and move expired workspaces into the
+grace period.
+
+In addition to this automatic process, you also have the option of **explicitly releasing
+workspaces** using the `ws_release` command. It is mandatory to specify the name of the
 workspace and the filesystem in which it is allocated:
 
 ```console
@@ -344,17 +349,24 @@ marie-numbercrunch-1701873907
 ```
 
 In this example, the user `marie` has two inactive, i.e., expired, workspaces namely
-`test-workspace` in `horse`, as well as numbercrunch in the `walrus` filesystem. The command
+`test-workspace` in `horse`, as well as `numbercrunch` in the `walrus` filesystem. The command
 `ws_restore --list` lists the name of the workspace and its expiration date. As you can see, the
-expiration date is added to the workspace name as Unix timestamp.
+expiration date in Unix timestamp format is added to the workspace name.
 
-!!! hint "Deleting data in in an expired workspace"
+!!! hint "Deleting data in an expired workspace"
 
     If you are short on quota, you might want to delete data in expired workspaces since it counts
     to your quota. Expired workspaces are moved to a hidden directory named `.removed`. The access
     rights remain unchanged. I.e., you can delete the data inside the workspace directory but you
     must not delete the workspace directory itself!
 
+!!! warning
+
+    When you release a workspace **manually**, it will not receive a grace period and be
+    **permanently deleted** the **next day**. The advantage of this design is that you can create
+    and release workspaces inside jobs and not pollute the filesystem with data no one needs anymore
+    in the hidden directories (when workspaces are in the grace period).
+
 #### Expire Process
 
 The clean up process of expired workspaces is automatically handled by a so-called expirer process.
@@ -370,42 +382,62 @@ It performs the following steps once per day and filesystem:
 ### Restoring Expired Workspaces
 
 At expiration time your workspace will be moved to a special, hidden directory. For a month,
-you can still restore your data **into an existing workspace**.
+you can still restore your data **into an existing workspace** using the command `ws_restore`.
 
-!!! warning
+The expired workspace has to be specified by its full name as listed by `ws_restore --list`,
+including username prefix and timestamp suffix. Otherwise, it cannot be uniquely identified. The
+target workspace, on the other hand, must be given with just its short name, as listed by `ws_list`,
+without the username prefix.
 
-    When you release a workspace **by hand**, it will not receive a grace period and be
-    **permanently deleted** the **next day**. The advantage of this design is that you can create
-    and release workspaces inside jobs and not flood the filesystem with data no one needs anymore
-    in the hidden directories (when workspaces are in the grace period).
+Both workspaces must be on the **very same filesystem**. The data from the old workspace will be
+moved into a directory in the new workspace with the name of the old one. This means a newly
+allocated workspace works as well as a workspace that already contains data.
 
-Use
+!!! note "Steps for restoring a workspace"
 
-```console
-marie@login$ ws_restore --list
-horse:
-marie-test-workspace-1701873807
-    unavailable since Wed Dec  6 15:43:27 2023
-walrus:
-marie-numbercrunch-1701873907
-    unavailable since Wed Dec  6 15:45:07 2023
-```
+    1. Use `ws_restore --list` to list all your expired workspaces and get the correct identifier
+       string for the expired workspace. The identifier string of an expired and an active workspace
+       are different!
+    1. (Optional) Allocate a new workspace on the very same filesystem using `ws_allocate`.
+    1. Then, you can invoke `ws_restore <workspace_name> <target_name>` to restore the expired
+       workspace into the active workspace.
 
-to get a list of your expired workspaces, and then restore them like that into an existing, active
-workspace 'new_ws':
+??? example "Restore workspace `number_crunch` into new workspace `long_computations`"
 
-```console
-marie@login$ ws_restore --filesystem horse marie-test-workspace-1701873807 new_ws
-```
+    This example depictes the necessary steps to restore the expired workspace `number_crunch` into
+    a newly allocated workspace named `long_computations.`
 
-The expired workspace has to be specified by its full name as listed by `ws_restore --list`,
-including username prefix and timestamp suffix (otherwise, it cannot be uniquely identified). The
-target workspace, on the other hand, must be given with just its short name, as listed by `ws_list`,
-without the username prefix.
+    **First step**: List expired workspaces and retrieve correct identifier for the expired workspace.
+    In this example, `marie` has two expired workspaces, namely `test-workspace` and `number_crunch`
+    both in the `horse` filesystem. The identifier for the restore command is
+    `marie-number_crunch-1701873907`.
+
+    ```console
+    marie@login$ ws_restore --list
+    horse:
+    marie-test-workspace-1701873807
+        unavailable since Wed Dec  6 15:43:27 2023
+    marie-number_crunch-1701873907
+        unavailable since Wed Dec  6 15:45:07 2023
+    walrus:
+    ```
+
+    **Second step:** Allocate new workspace `long_compuations` on the very same filesystem. Please
+    refer to the documentation of the [`ws_allocate` command](#allocate-a-workspace) for
+    additional useful options.
 
-Both workspaces must be on the same filesystem. The data from the old workspace will be moved into
-a directory in the new workspace with the name of the old one. This means a fresh workspace works as
-well as a workspace that already contains data.
+    ```console
+    marie@login$ ws_allocate --filesystem horse --name long_computations --duration 60
+    ```
+
+    **Third step:** Invoke the command `ws_restore`.
+
+    ```console
+    marie@login$ ws_restore --filesystem horse marie-number_crunch-1701873907 long_computations
+    to verify that you are human, please type 'menunesarowo': menunesarowo
+    you are human
+    Info: restore successful, database entry removed.
+    ```
 
 ## Linking Workspaces in HOME