- Finalizing the documentation before tagging 1.0 release

docs/01-echoing.md

@@ -0,0 +1,73 @@
+# Echoing text or data
+
+There is two token groups that you can use to print content into a view, `echo` or `print`.
+
+Escaped by default : `{% echo $argument %}` = `{{ $argument }}` = `{% print $argument %}`
+
+Raw when needed: `{% echo.raw $argument %}` = `{{= $argument }}` = `{% print.raw $argument %}`
+
+## Outputing content to a view using `echo` / `{{ }}` / `print`, `echo.raw` / `{{= }}` / `print.raw`
+
+Using `print` or `echo`, which are, by default, made safer by using PHP's native `htmlspecialchars`.
+
+**[PICEA]** So, using this code:
+
+```html
+{{ "Hello World !" }}
+
+{% echo "This is another way to output <safe> content" %}
+
+{% print "This is the third way to output <safe> content" %}
+
+<hr>
+
+{% echo.raw $someHTML %}
+
+{% print.raw $someOtherHTML %}
+
+{{= $someMoreHTML }}
+```
+
+**[PHP]** Would yield internally:
+
+```php
+<?php echo htmlspecialchars((string) "Hello World !", 3, 'UTF-8', true) ?>
+
+<?php echo htmlspecialchars((string) "This is another way to output &lt;safe&gt; content", 3, 'UTF-8', true) ?>
+
+<?php echo htmlspecialchars((string) "This is another way to output &lt;safe&gt; content", 3, 'UTF-8', true) ?>
+
+<hr>
+
+<?php echo $someHTML ?>
+
+<?php echo $someOtherHTML ?>
+
+<?php echo $someMoreHTML ?>
+```
+
+## Using string format variant `printf` / `printf.raw`
+
+Those tokens represents the equivalent of the printf() function from PHP.
+
+**[PICEA]** So, using this code:
+
+```html
+{% php 
+    $num = 5;
+    $location = 'tree';
+%}
+<span>{% printf 'There are %d monkeys in the %s', $num, $location %}</span>
+<i>{% printf.raw 'There are %d monkeys in the %s', $num, $location %}</i>
+```
+
+**[PHP]** Would render internally as :
+
+```php
+<?php 
+    $num = 5; 
+    $location = 'tree';
+?>
+<span><?php echo htmlspecialchars((string) sprintf('There are %d monkeys in the %s', $num, location), 3, 'UTF-8', true); ?></span>
+<i><?php printf('There are %d monkeys in the %s', $num, location) ?></i>
+```