clarify what is meant by standalone

[softprops]

There are a number of places in the specs that mention an entity should be treated one way if it is standalone and another if it is not without giving any definition of what it means to be standalone. Can someone please elaborate what exactly it means to be standalone?

[groue]

I guess a tag is "standalone" when it is the only non-whitespace token on a line.

[zombiezen]

I guess a tag is "standalone" when it is the only non-whitespace token on a line.

This doesn't appear to be the full definition, especially with respect to parent tags. For example, the "Inherit" test case in ~inheritance.yml seems to imply that {{<include}}{{/include}}\n counts as standalone tags.

EDIT: And this is made more explicit in other standalone cases in the inheritance test suite.

[jgonggrijp]

@softprops @zombiezen Does #131 address your question? An even more elaborate version can be found in #130.

To be fair to @groue, parent tag pairs were not included in the spec yet when he wrote his reply.

[zombiezen]

The test cases paint a clear picture, yes! I came across this issue because although the test cases are very precise and I was able to deduce the intended behavior through experimentation, the prose in the various overviews mention "standalone" without giving a definition. IMO, it would be nice to give a non-normative explanation for readers, but I don't think there's anything in the test cases that need to change.

[jgonggrijp]

I meant the GitHub comments (including the opening post) that came with #131 (and #130), rather than the tests introduced by #131.

Does that prose satisfy your wish or are you still looking for something less normative? Could you perhaps refer to a nonnormative description of another Mustache feature that you wish the standalone description could mimic?

[zombiezen]

Ah that makes more sense. Yes, that prose is incredibly helpful for understanding the intended behavior, thank you. If the summary in #131 was added to the inheritance extension's overview with a couple tweaks, IMO that would help future readers tremendously.

A few specific suggestions based on trying to use that prose to pass the test cases:

• Include definitions from Proposal on how to specify indentation of blocks #130 for terms like "clear", "argument blocks", and "parameter blocks".
• There's probably a way to rephrase rule 3 to avoid the term "definition", since I got the idea that deindenting needs to occur for the block.
• The phrase "standalone parameter block" in rule 2 packs a lot of subtlety in three words. Not necessarily bad, but it took me a few reads to understand the implications of it.
• Rule 2 has a bit of an unintended interaction with the phrase "with intrinsic indentation" in Rule 4. Because Rule 2 has a definition for intrinsic indentation for all blocks, an incorrect but plausible reading of Rule 4 is the intrinsic indentation is used for all blocks, whereas IIUC the intent is to only use the intrinsic indentation for the opening tag of an argument block or a standalone parameter block that clears at the end. I think repeating that condition is more clear than "with intrinsic indentation".

Hope that's helpful. Thank you for the pointers and your thoroughness! 🙂

[jgonggrijp]

@zombiezen I'm not entirely opposed to adding documentation about the whitespace handling rules to the spec overviews. That being said, I'm a bit worried that a disproportional amount of text will be dedicated to whitespace handling rather than the core semantics of partials and inheritance. The main idea is that we try to make Mustache handle whitespace exactly in the way that the human end user would intuitively expect; the complexity of the whitespace rules is a side effect of human intuition being subtle and nuanced.

Other than putting all of that prose in the overviews, I can think of two other options:

• Add a whitespace.md to the specs directory that has all the prose about whitespace handling. The actual specs can refer to it for clarification.
• Simply refer to Additional inheritance specs for block reindentation #131 and Proposal on how to specify indentation of blocks #130 in the specs, possibly after editing the opening posts a bit for clarification.

If either of these options appeals to you, you would be welcome to submit a pull request as far as I'm concerned.

• There's probably a way to rephrase rule 3 to avoid the term "definition", since I got the idea that deindenting needs to occur for the block.

How about "compile time block deindentation"?

• The phrase "standalone parameter block" in rule 2 packs a lot of subtlety in three words. Not necessarily bad, but it took me a few reads to understand the implications of it.

Understandable. #131 is a condensed version of #130, where it comes with an interjection "so that's BB, BS, BE, BN, EB, ES, EE or EN for argument blocks but only BB or BE for parameter blocks".

• Rule 2 has a bit of an unintended interaction with the phrase "with intrinsic indentation" in Rule 4. Because Rule 2 has a definition for intrinsic indentation for all blocks, an incorrect but plausible reading of Rule 4 is the intrinsic indentation is used for all blocks, whereas IIUC the intent is to only use the intrinsic indentation for the opening tag of an argument block or a standalone parameter block that clears at the end. I think repeating that condition is more clear than "with intrinsic indentation".

Yes, I think you are right.

Hope that's helpful. Thank you for the pointers and your thoroughness! 🙂

Welcome!

[zombiezen]

I'm not entirely opposed to adding documentation about the whitespace handling rules to the spec overviews. That being said, I'm a bit worried that a disproportional amount of text will be dedicated to whitespace handling rather than the core semantics of partials and inheritance.

A very reasonable concern. Agreed.

Other than putting all of that prose in the overviews, I can think of two other options:

A whitespace.md file sounds like the best approach to me. That way, the specification is self-contained and further edits can go through the normal review process and be versioned with the rest of the test cases.

If either of these options appeals to you, you would be welcome to submit a pull request as far as I'm concerned.

Lovely! I'll send something over this week.