From 178d4e2190c69f8aedc9b9bec0f1bcfe4d0a0299 Mon Sep 17 00:00:00 2001
From: laniakea64 <laniakea64@users.noreply.github.com>
Date: Mon, 20 May 2024 15:31:03 -0400
Subject: [PATCH] Improve `shell()` documentation (#2060)

---
 README.md | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index d67efc5..3b4ae61 100644
--- a/README.md
+++ b/README.md
@@ -1342,7 +1342,7 @@ file.
 
 #### External Commands
 
-- `shell(command, args...)` returns the standard output of shell script
+- `shell(command, args...)`<sup>master</sup> returns the standard output of shell script
   `command` with zero or more positional arguments `args`. The shell used to
   interpret `command` is the same shell that is used to evaluate recipe lines,
   and can be changed with `set shell := […]`.
@@ -1360,24 +1360,25 @@ file.
   expected to be the name of the program being run.
 
 ```just
-# arguments can be variables
+# arguments can be variables or expressions
 file := '/sys/class/power_supply/BAT0/status'
 bat0stat := shell('cat $1', file)
 
-# commands can be variables
-command := 'wc -l $1'
-output := shell(command, 'main.c')
+# commands can be variables or expressions
+command := 'wc -l'
+output := shell(command + ' "$1"', 'main.c')
 
-# note that arguments must be used
+# arguments referenced by the shell command must be used
 empty := shell('echo', 'foo')
 full := shell('echo $1', 'foo')
+error := shell('echo $1')
 ```
 
 ```just
 # Using python as the shell. Since `python -c` sets `sys.argv[0]` to `'-c'`,
 # the first "real" positional argument will be `sys.argv[2]`.
 set shell := ["python3", "-c"]
-olleh := shell('import sys; print(sys.argv[2][::-1]))', 'hello')
+olleh := shell('import sys; print(sys.argv[2][::-1])', 'hello')
 ```
 
 #### Environment Variables