docs/builder: add note about handling of leading whitespace

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

docs/reference/builder.md

@@ -191,6 +191,34 @@ RUN echo 'we are running some # of cool things'
 
 Line continuation characters are not supported in comments.
 
+> **Note on whitespace**
+>
+> For backward compatibility, leading whitespace before comments (`#`) and
+> instructions are ignored, but not recommended. The leading whitespace is not
+> preserved, and the following examples are therefore equivalent:
+>
+> ```dockerfile
+>         # this is a comment-line
+>     RUN echo hello
+> RUN echo world
+> ```
+> 
+> ```dockerfile
+> # this is a comment-line
+> RUN echo hello
+> RUN echo world
+> ```
+> 
+> However, whitespace in instruction arguments, such as `RUN` are always preserved,
+> so the following example prints `    hello    world` with leading whitespace as
+> specified:
+>
+> ```dockerfile
+> RUN echo "\
+>      hello\
+>      world"
+> ```
+
 ## Parser directives
 
 Parser directives are optional, and affect the way in which subsequent lines