diff options
| -rw-r--r-- | man/blogc-template.7.ronn | 164 | ||||
| -rw-r--r-- | man/index.txt | 1 |
2 files changed, 160 insertions, 5 deletions
diff --git a/man/blogc-template.7.ronn b/man/blogc-template.7.ronn index 5883d09..98ceab5 100644 --- a/man/blogc-template.7.ronn +++ b/man/blogc-template.7.ronn @@ -1,13 +1,167 @@ blogc-template(7) -- blogc's template format ============================================ -## SYNOPSIS +## DESCRIPTION -TODO +Template files are used as base to build output files by blogc(1). These files +can include variables, blocks and conditionals, that will directly affect the +output files. -## DESCRIPTION +The syntax of the template files is defined to be simple, without affecting the +content output. The syntax is somewhat inspired by Jinja2 syntax. + +This manual describes the basic syntax and functionalities of template files. + +## TEMPLATE BLOCKS + +Template blocks are used to delimit content. The content inside a block will +be included in the output file (or not) if the parameters passed to blogc(1) +matches the requirements of the given block. + +Blocks can be defined more than once, but can't be nested. + +The available blocks are: `entry`, `listing` and `listing_once`. + +### entry block + +The content of an `entry` block is included in the output file when blogc(1) +is called without `-l` option, and with only one source file. It is used to +render a single entry of your blog/website. All the variables defined in the +source file are available inside this block (see blogc-source(7)), and will +override global variables (see blogc(1)). + +This is how an `entry` block is defined: + + {% block entry %} + This content will only be included when rendering a single entry. + {% endblock %} + +### listing block + +The content of a `listing` block is included in the output file when blogc(1) +is called with `-l` option, and with one or more source files. It is used +to create a listing of entries, and its content will be included once for +each given source file (in the order that the source files were provided to +blogc(1)). All the variables defined in the source files are available +inside this block (see blogc-source(7)), and will override global variables +(see blogc(1)). The variables will be provided by each file, when blogc(1) +iterates over them. + +This is how a `listing` block is defined: + + {% block listing %} + This content will be only included when rendering an entry listing, and + will be included once for each entry. + {% endblock %} + +### listing_once block + +The content of a `listing_once` block is included in the output file when +blogc(1) is called with `-l` option, and with one or more source files. It is +like a `listing` block, but is only called once, and does not have access +to the local variables defined in the source files. It is useful to add +something before an entry listing. + +This is how a `listing_once` block is defined: + + {% block listing_once %} + This content will be only included when rendering an entry listing, but + will be included only once. + {% endblock %} + +This is a 'real life' usage example of a `listing_once` block, supposing +that each source file defines a `TITLE` variable: + + {% block listing_once %} + <ul> + {% endblock %} + {% block listing %} + <li>{{ TITLE }}</li> + {% endblock %} + {% block listing_once %} + </ul> + {% endblock %} + +## TEMPLATE VARIABLES + +Template variables are used to provide content to templates from blogc(1) +command-line and from source files. + +This is how a variable is defined in a template: + + {{ VARIABLE_NAME }} + +The value of a variable will depends of its scope. Global variables provided +to blogc(1) are available everywhere in the templates. Local variables +provided in the source files are available only inside `entry` and `listing` +blocks, and will override global variables. + +If a variable is not defined, it will be replaced by an empty string. blogc(1) +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). + +## TEMPLATE CONDITIONALS + +Template conditionals are used to include content to the output, or not, +based on the value and existence of variables in the current scope. + +The implementation of conditionals is simple, and each will just evaluate the +value of a single variable. + +The available conditionals are: `ifdef`, `ifndef` and `if`. + +### ifdef conditional + +The content of an `ifdef` conditional is included in the output file when +the given variable is defined in the current scope. + +This is how an `ifdef` conditional is defined in a template: + + {% ifdef TITLE %} + This is title: {{ TITLE }} + {% endif %} + +In this case, if the `TITLE` variable is defined, the content is included. + +### ifndef conditional + +The content of an `ifndef` conditional is included in the output file when +the given variable is not defined in the current scope. + +This is how an `ifndef` conditional is defined in a template: + + {% ifndef TITLE %} + Untitled entry + {% endif %} + +In this case, if the `TITLE` variable is not defined, the content is included. + +### if confitional + +The content of an `if` conditional is included in the output file when +the comparision between the given variable and the static string evaluates to +true in the current scope. + +The available operators are: `==`, `!=`, `<`, `>`, `<=` and `>=`. The +comparisions are strcmp(3)-like. + +This is how an `if` conditional is defined in a template: + + {% if TITLE == "My Title" %} + Title is "My Title" + {% endif %} + +## BUGS + +The source content is handled by handwritten parsers, that even being well +tested, may be subject of parsing bugs. Please report any issues to: +<https://github.com/blogc/blogc> -TODO +At least one bug is known at this point: ``\r\n`` character sequences are +handled like 2 line breaks. The parsers won't work properly with files edited +on Windows editors like Notepad. ## AUTHOR @@ -15,4 +169,4 @@ Rafael G. Martins <<rafael@rafaelmartins.eng.br>> ## SEE ALSO -blogc(1) +blogc(1), blogc-source(7) diff --git a/man/index.txt b/man/index.txt index 4ff99f5..a85e2a0 100644 --- a/man/index.txt +++ b/man/index.txt @@ -5,4 +5,5 @@ blogc-template(7) blogc-template.7.ronn # external manuals make(1) http://man.cx/make(1) +strcmp(3) http://man.cx/strcmp(3) strptime(3) http://man.cx/strptime(3) |