From f76ff3e96a1cc1c60dbb9471790ebef8e1cc9732 Mon Sep 17 00:00:00 2001
From: Mike Frysinger <vapier@google.com>
Date: Mon, 13 Apr 2020 21:29:10 -0400
Subject: [PATCH] Project import generated by Copybara.

PiperOrigin-RevId: 306352475
---
 shellguide.md | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/shellguide.md b/shellguide.md
index 7769f60..0c59fbb 100644
--- a/shellguide.md
+++ b/shellguide.md
@@ -809,8 +809,16 @@ mybinary ${flags}
 # Command expansions return single strings, not arrays. Avoid
 # unquoted expansion in array assignments because it won’t
 # work correctly if the command output contains special
-# characters.
+# characters or whitespace.
+
+# This expands the listing output into a string, then does special keyword
+# expansion, and then whitespace splitting.  Only then is it turned into a
+# list of words.  The ls command may also change behavior based on the user's
+# active environment!
 declare -a files=($(ls /directory))
+
+# The get_arguments writes everything to STDOUT, but then goes through the
+# same expansion process above before turning into a list of arguments.
 mybinary $(get_arguments)
 ```