From 84f6e7db2e7aee8b2f13d75dbde0985d25f6c8ed Mon Sep 17 00:00:00 2001
From: Bart Oldeman <bartoldeman@gmail.com>
Date: Wed, 17 Jan 2024 14:48:06 -0500
Subject: [PATCH] Further documentation for `run_shell_cmd`

---
 docs/easybuild-v5/run_shell_cmd.md | 37 ++++++++++++++++++++++--------
 1 file changed, 28 insertions(+), 9 deletions(-)

diff --git a/docs/easybuild-v5/run_shell_cmd.md b/docs/easybuild-v5/run_shell_cmd.md
index c1a1e786d..540692c91 100644
--- a/docs/easybuild-v5/run_shell_cmd.md
+++ b/docs/easybuild-v5/run_shell_cmd.md
@@ -8,18 +8,13 @@ This function replaces both the `run_cmd` and `run_cmd_qa` functions, which will
 
 ## Motivation
 
-...
+Over the years `run_cmd` and `run_cmd_qa` accumulated a lot of arguments which sometimes have misleading names.
+Moreover they have two different kinds of return values (depending on whether called with `simple=True` or `simple=False`).
+So a new command `run_shell_cmd` is introduced to replace both, using more direct and natural arguments, and as a bonus,
+better error reporting. In line with `--trace` being set by default, `run_shell_cmd` is now also more verbose by default.
 
 ## High-level overview
 
-...
-
-## Use cases
-
-...
-
-## Transitioning from `run_cmd` to `run_shell_cmd`
-
 First of all `run_shell_cmd` has been designed so the defaults can be used for most situations.
 In that case the main thing to watch out for is the return code, which changed from a tuple `(output, exit_code)`
 to a named tuple with three fields:
@@ -41,6 +36,28 @@ res = run_shell_cmd(cmd)
 out = res.output
 ```
 
+## Use cases
+
+Examples:
+
+- Basic use
+
+  ```python
+  cmd = ' '.join([self.cfg['preinstallopts'], install_cmd, self.cfg['installopts']])
+  run_shell_cmd(cmd)
+  ```
+
+- Get error code for both failure and non-failure of the command, as otherwise `run_shell_cmd` will raise `RunShellCmdError`. Additionally, don't display this command in terminal output:
+
+  ```python
+  cmd = "cmake --version"
+  res = run_shell_cmd(cmd, hidden=True, fail_on_error=False)
+  out = res.output
+  ec = res.code
+  ```
+
+## Transitioning from `run_cmd` to `run_shell_cmd`
+
 For parameters in general, the following translation table can be used, where the default values are shown:
 
 | run_cmd parameter    |run_shell_cmd parameter| meaning |
@@ -67,4 +84,6 @@ For parameters in general, the following translation table can be used, where th
 
 ## Transitioning from `run_cmd_qa` to `run_shell_cmd`
 
+This is still to be implemented in `run_shell_cmd`.
+
 ...