From 5168f9862be5ab925bafc1df567867fdfca82ca4 Mon Sep 17 00:00:00 2001 From: "Rafael G. Martins" Date: Sun, 10 Feb 2019 23:18:34 +0100 Subject: man: added documentation for predefined template variables --- man/blogc-template.7.ronn | 47 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/man/blogc-template.7.ronn b/man/blogc-template.7.ronn index 1caa839..afa884b 100644 --- a/man/blogc-template.7.ronn +++ b/man/blogc-template.7.ronn @@ -137,6 +137,53 @@ 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. +## PREDEFINED TEMPLATE VARIABLES + +blogc(1) provides some template variables, that can be used to display some build +metadata in your website. + +If some of the variables are not available in the system running the build, they +won't be defined. It is recommended to rely on template conditionals, mainly +`ifdef` and `ifndef` when using these variables. + +### Static variables + +These variables are always available, and are set during the blogc(1) binary +compilation. + + * `BLOGC_VERSION`: + The version of blogc(1) used to build. e.g.: `blogc 0.14.1`. + +### Resource usage variables + +It is not possible to measure the resource usage of blogc(1) until the end of +the execution, because the rendering of these variables itself is using resources, +and the evaluation of the used resources was already done. To get better values, +it is recommended to use these variables only in the website footer. + + * `BLOGC_RUSAGE_CPU_TIME`: + The CPU time used to build, up to the point where this variable was used for + the first time in the template (value is cached). e.g.: `12.345ms`. + + * `BLOGC_RUSAGE_MEMORY`: + The memory used to build, up to the point where this variable was used for the + first time in the template (value is cached). e.g.: `1.234MB`. + +### System information variables + + * `BLOGC_SYSINFO_HOSTNAME`: + The hostname of the machine where the build happened (short hostname only, not + FQDN). + + * `BLOGC_SYSINFO_USERNAME`: + The username of the user that executed the build. + + * `BLOGC_SYSINFO_DATETIME`: + The GMT datetime of the build. e.g. `2019-02-10 22:00:00`. + + * `BLOGC_SYSINFO_INSIDE_DOCKER`: + If built inside a docker container, this variable will be defined, with value `1`. + ## TEMPLATE CONDITIONALS Template conditionals are used to include content to the output, or not, -- cgit v1.2.3-18-g5258