renderer: added support to truncate variables.

this commit also documents variable formatters properly.

2 files changed, 39 insertions, 1 deletions

diff --git a/man/blogc-source.7.ronn b/man/blogc-source.7.ronn
index 9a0c94c..5bb3b32 100644
--- a/man/blogc-source.7.ronn
+++ b/man/blogc-source.7.ronn
@@ -55,7 +55,9 @@ parser. It contains the unparsed content of the first paragraph found in the
 source file. The content is not parsed but HTML entities are encoded. Paragraphs
 inside blockquotes are ignored. This variable can be overriden by an explicit
 definition in source file, that must have the HTML entities escaped manually.
-This is useful to add "description" meta-tags to HTML templates.
+This is useful to add "description" meta-tags to HTML templates. It may be
+needed to truncate the variable size to an maximum length, take a look at
+blogc-template(7).
 
 ## SOURCE CONTENT - BLOCK ELEMENTS
 
diff --git a/man/blogc-template.7.ronn b/man/blogc-template.7.ronn
index bd38618..3499d7c 100644
--- a/man/blogc-template.7.ronn
+++ b/man/blogc-template.7.ronn
@@ -105,6 +105,36 @@ won't raise any error in this case.
 Variables are always strings, even if the value of the variable is a number,
 it is handled as a string by blogc(1).
 
+### Variable formatters
+
+blogc(1) can apply a formatter to a variable, depending on how it is called
+in the template. If user append `_FORMATTED` to the end of the variable name,
+a formatter will be applied, if available for the variable name:
+
+- Date formatter: if variable name starts with `DATE_`, it is formatted with
+  a strptime(3) format, provided by `DATE_FORMAT` variable. The `DATE_FORMATTED`
+  "meta-variable" will return the formatted version of the `DATE` variable.
+  If `DATE_FORMAT` is not provided, the original value will be returned.
+
+An existing variable is not overrided by formatter. That means that if
+`FOO_FORMATTED` variable exists, it won't be handled as a formatter
+"meta-variable", and `FOO_FORMATTED` variable value will be returned normally.
+
+### Truncated variables
+
+blogc(1) can truncate the value of a variable to a maximum length, if it is
+called with the maximum length appended to the end of the variable, like:
+`FOO_5` will return the 5 first characters of the `FOO` variable, if bigger
+than 5 characters.
+
+This is applicable to the "meta-variables", like `DATE_FORMATTED`. It can
+be truncated like: `DATE_FORMATTED_5`, that will return the 5 first
+characters of the `DATE_FORMATTED` "meta-variable".
+
+An existing variable is not overrided by the truncate syntax. That means
+that if `FOO_5` variable exists, it won't be handled as a truncate
+"meta-variable", and `FOO_5` variable value will be returned normally.
+
 ## TEMPLATE CONDITIONALS
 
 Template conditionals are used to include content to the output, or not,
@@ -199,6 +229,12 @@ iteration.
 If the value of the `TAGS` variable is "item1 item2 item3", this template is
 rendered 3 times, one for each item value.
 
+The `FOREACH_ITEM` variable can be truncated, like:
+
+    {% foreach TAGS %}
+    <a href="/tag/{{ FOREACH_ITEM }}/">{{ FOREACH_ITEM_5 }}</a>
+    {% endforeach %}
+
 ## WHITESPACE CONTROL
 
 Users can control how whitespaces (space, form-feed (`\f`), newline (`\n`),