diff --git a/src/main/java/com/google/devtools/build/docgen/templates/be/make-variables.vm b/src/main/java/com/google/devtools/build/docgen/templates/be/make-variables.vm
index 5bc19b8..9e2fe53 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/be/make-variables.vm
+++ b/src/main/java/com/google/devtools/build/docgen/templates/be/make-variables.vm
@@ -229,6 +229,24 @@
   </li>
 </ul>
 
+<p>
+  <b>Note:</b> If the filenames corresponding to the input labels or the output
+  filenames contain spaces, <code>'</code>, or other special characters (or your
+  genrule is part of a Starlark macro which downstream users may invoke on such
+  files), then <code>$(SRCS)</code> and <code>$(OUTS)</code> are not suitable
+  for interpolation into a command line, as they do not have the semantics that
+  <code>"${@}"</code> would in Bash.
+</p>
+<p>One workaround is to convert to a Bash array, with
+  <pre><code>mapfile SRCS <<< "$$(sed -e 's/ /\\n/g' <<'genrule_srcs_expansion'
+$(SRC)
+genrule_srcs_expansion
+)</code></pre>
+and then use <code>"$$\{SRCS[@]}"</code> in subsequent command lines in place
+of <code>$(SRCS)</code>. A more robust option is to write a Starlark rule
+instead.
+</p>
+
 
 <h2 id="predefined_label_variables">Predefined source/output path variables</h2>
 <p>