From b55d22d60219cb65afda11ea81a4486b4a69eb23 Mon Sep 17 00:00:00 2001
From: Roxy Light <roxy@256lights.llc>
Date: Sat, 1 Mar 2025 16:46:53 -0800
Subject: [PATCH] Add whitespace guidance document

This document summarizes #130 and #131 for future readers.
I tried to minimize the use of jargon
and included representative examples to introduce each concept.

After careful consideration, I included a short glossary to introduce some terms.
The prose kept coming out clunky when I tried to define the terms in the middle of defining "standalone",
so introducing them upfront seemed like a clearer flow.
Rather than use the term "pair",
I borrowed the term "element" from HTML since the concept is analogous.

Fixes #65
---
 specs/whitespace.md | 107 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 107 insertions(+)
 create mode 100644 specs/whitespace.md

diff --git a/specs/whitespace.md b/specs/whitespace.md
new file mode 100644
index 0000000..4d38377
--- /dev/null
+++ b/specs/whitespace.md
@@ -0,0 +1,107 @@
+# Whitespace in Mustache
+
+*(This document is non-normative and summarizes the whitespace rules presented in the specs for implementation authors.)*
+
+## Terms
+
+<dl>
+<dt>element</dt>
+<dd>A section, inverted section, parent, or block tag plus its content up to and including its associated end tag. For example, <code>{{$foo}}bar{{/foo}}</code> is a single block element.</dd>
+<dt>argument block</dt>
+<dd>A block element that is a direct child of a parent tag.</dd>
+<dt>parameter block</dt>
+<dd>A block element that is not a direct child of a parent tag.</dd>
+</dl>
+
+## Standalone tags and elements
+
+Mustache tries to avoid adding undesired blank lines for non-interpolation tags.
+For example, assuming that `boolean = true`, the following template:
+
+```mustache
+| This Is
+{{#boolean}}
+|
+{{/boolean}}
+| A Line
+```
+
+will render as:
+
+```plain
+| This Is
+|
+| A Line
+```
+
+instead of:
+
+```plain
+| This Is
+
+|
+
+| A Line
+```
+
+A tag is considered **standalone** if the tag is the only text on the line except whitespace.
+Interpolation tags are never considered standalone.
+The leading whitespace, trailing whitespace, and line ending of a standalone tag are ignored.
+
+Additionally, parent elements and parameter blocks
+are considered standalone if the start tag has zero or more whitespace characters preceding it on its line
+and its associated end tag has zero or more whitespace characters following it on its line.
+In such cases, the leading whitespace of such a parent tag or parameter block's start tag,
+the trailing whitespace of the associated end tag,
+and the line ending of the associated end tag are ignored.
+
+## Indentation
+
+Mustache tries to keep indentation consistent when using partials, parents, and blocks.
+For example, for the following template:
+
+```mustache
+{{<parent}}{{$block}}
+    one
+    two
+{{/block}}{{/parent}}
+```
+
+and the following definition of `parent`:
+
+```mustache
+Hi,
+  {{$block}}
+  {{/block}}
+```
+
+the template will render as:
+
+```plain
+Hi,
+  one
+  two
+```
+
+instead of:
+
+```plain
+Hi,
+      one
+      two
+```
+
+If a block tag is at the end of a line (ignoring any trailing whitespace)
+and it is either part of an argument block or part of a standalone parameter block,
+then the block element's **intrinsic indentation** is the sequence of leading whitespace characters on the line following the block tag.
+Otherwise, the block element's intrinsic indentation is the empty string.
+Mustache implementations must ignore the occurrence of the block element's intrinsic indentation
+at the beginning of each line of the block element's content.
+
+When a standalone partial tag or standalone parent element is expanded,
+the leading whitespace on the start tag's line is prepended to each line of the expanded template.
+A similar behavior occurs for standalone parameter blocks.
+If a standalone parameter block's start tag is at the end of a line (possibly with trailing whitespace),
+then its intrinsic indentation is prepended to each line of the argument block that is overriding it.
+Otherwise, the leading whitespace of the standalone parameter block's start tag
+is prepended to each line of the argument block that is overriding it.