[policy, no patch] Decide how to document Twig template files

I'm +1 for this too. I think that it could be confusing if you are referring to a variable if it's not in this format.

for sure ... I missed the hangout yesterday but actually this morning updated the template conversions instructions docs toward the bottom with this {{ item }} full syntax

Please confirm we want to do that from themers perspective.

Bumping up to critical as we need to solve this.

Assigning to @chx for another round of twitter poll review.

The question is:

- variable - description

in docs

OR:

- {{ variable }} - description

in docs.

Discussed with chx.

We have a docs core policy for twig files in #1759168: Comments in twig files [policy, no patch].

The problem is:

{{ var }}  == echo $var

Using {{ var }} in docs would imply {% if {{ var }} %}, which is wrong ...

=> We need to use the simplified version, lets continue discussions in #1759168: Comments in twig files [policy, no patch] - if there is more need.

We talked about this in the weekly twig meeting today, and we decided that the existing syntax should be sufficient.

In PHPTemplate, we did NOT write this in the docs:

/**
 * @file
 * Default theme implementation to display a node.
 *
 * Available variables:
 * - <?php print $title ?>: the (sanitized) title of the node.
 ...

so there is no reason to include the print statements for Twig, either.

There will be plenty of examples how the variable is being printed, and evaluated, in the Twig code below, and we expect most front-end devs to copy and paste from there as well.

Or we could surround the variable in single quotes or something. I dislike the idea of using the print syntax in sentences since I think it might confuse people, especially when the sentences are talking about testing the values of variables - in those cases using the print syntax would be wrong.

"So this is how you use the 'element' variable. You can test it in a conditional statement: {% if element == 'h3' %}. You can print output its value like this: {{ element }} ."

compared to

"So this is how you use the element variable. You can test it in a conditional statement: {% if element == 'h3' %}. You can print output its value like this: {{ element }} ."

While my first thought is that single quotes looks nicer (first example), maybe no wrapper (as in the second example) might help us avoid people trying to use the variable WITH the surrounding single quotes. Most people probably will figure it out, but isn't it feasible that people may copy the 'element' variable with the quotes and try to use that when instead they should be using element without quotes?

It may be a little less clear to read? without any quotes, but for the case of people wanting to copy and paste, etc... maybe no wrapper could be a safe option?