From 4cd15fad3cf1252532da170e44dad68683601166 Mon Sep 17 00:00:00 2001 From: p4bl0 Date: Wed, 11 Aug 2010 11:15:46 +0200 Subject: started to write the template system doc in the README --- README | 202 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ html-gen.sh | 2 + 2 files changed, 204 insertions(+) diff --git a/README b/README index 755e46e..3165d2b 100644 --- a/README +++ b/README @@ -152,4 +152,206 @@ fugitive: README Do not create an article file named "index".

Template system

+

+ The better explaination about the templates system is to see what the default + templates looks like. But since they do not use all the offered + possibilities, here are some more explainations... +

+

+ The fugitive template system uses xml preprocessor + syntax: <?fugitive var ?> is rendered as the + value of var. +

+

+ In addition to that, there are a conditional and a foreach loop constructs, + plus an include directive. +

+

+ The syntax of the include directive is <?fugitive + include:file ?> where file is relative to + the templates-dir directory + (see configuration). The includes are processed before + anything else. +

+

+ The foreach loop construct is specific to the "archives.html" and + "feed.xml" templates and will therefore be described at the same + time. Where available, the loops are processed right after the includes. +

+

+ The syntax of the conditional construct is as follow: +

+
<?fugitive ifset:var ?>
+  Template code which is ignored if var value is empty, and
+  which typically includes <code><?fugitive var ?></code>.
+<?fugitive endifset:var ?>
+

+ Not every variables can be used in the conditional construct, it is indicated + in the description od those which can't. +

+

The following variables are available everywhere:

+
+
page_title
+
+ Its value is "archives" in the archives.html template, + "feed" in the feed.xml template, or the article title in the + article.html template. +
+
blog_url
+
+ the blog-url value in the "fugitive" section of the git + configuration (see configuration). +
+
commit_Hash
+
+ Its value is the hash corresponding to the last commit that provoked the + (re)generation of the file. +
+
commit_hash
+
+ Its value is the short hash (the seven first digit of the hash) + corresponding to the last commit that provoked the (re)generation of the + file. +
+
commit_author
+
+ Its value is the name of the author of the last commit that provoked the + (re)generation of the file. +
+
commit_author_email
+
+ Its value is the email of the author of the last commit that provoked the + (re)generation of the file (with '@' replaced by "[at]" and '.' + replaced by "(dot)"). +
+
commit_datetime
+
+ Its value is the date and time of the last commit that provoked the + (re)generation of the file. +
+
commit_date
+
+ Its value is the date of the last commit that provoked the (re)generation + of the file. +
+
commit_time
+
+ Its value is the time of the last commit that provoked the (re)generation + of the file. +
+
commit_timestamp
+
+ Its value is the unix timestamp of the last commit that provoked the + (re)generation of the file. +
+
commit_subject
+
+ Its value is the subject (first line of the commit message) of the last + commit that provoked the (re)generation of the file. +
+
commit_body
+
+ Its value is the body (the rest of the commit message) of the last commit + that provoked the (re)generation of the file. This variable can't + be used in the conditional construct. +
+
commit_slug
+
+ Its value is the subject of the last commit that provoked the + (re)generation of the file but formatted to be file name friendly. +
+
+

Variables specific to the article.html templates:

+
+
article_title
+
+ Its value is the title of the article (the first line of the file). +
+
article_content
+
+ Its value is the content of the article (the rest of the + file). This variable can't be used in the conditional + construct. +
+
article_file
+
+ Its value is the file name of the article (without the .html extension). +
+
article_cdatetime
+
+ Its value is the date and time of the publication of the article (the date + of the commit which added the article to the repository in + the articles-dir directory + (see configuration)). +
+
article_cdate
+
+ Its value is the date of the publication of the article. +
+
article_ctime
+
+ Its value is the time of the publication of the article. +
+
article_ctimestamp
+
+ Its value is the timestamp of the publication of the article. +
+
article_mdatetime
+
+ Its value is the date and time of the last modification of the article + (the date of the last commit which changed the article file). +
+
article_mdate
+
+ Its value is the date of the last modification of the article. +
+
article_mtime
+
+ Its value is the time of the last modification of the article. +
+
article_mtimestamp
+
+ Its value is the timestamp of the last modification of the article. +
+
article_cauthor
+
+ Its value is the author of the commit which added the article to the + repository. +
+
article_cauthor_email
+
+ Its value is the email of the author of the commit which added the article + to the repository (with '@' replaced by "[at]" and '.' replaced + by "(dot)"). +
+
article_mauthor
+
+ Its value is the author of the last commit which changed the article file. +
+
article_mauthor_email
+
+ Its value is the email of the author of the last commit which changed the + article file (with '@' replaced by "[at]" and '.' replaced by + "(dot)"). +
+
article_previous_file
+
+ Its value is the file name (without .html extension) of the previous + article ordered by publication date. +
+
article_previous_title
+
+ Its value is the title of the previous article ordered by publication date. +
+
article_next_file
+
+ Its value is the file name (without .html extension) of the next article + ordered by publication date. +
+
article_next_title
+
+ Its value is the title of the next article ordered by publication date. +
+
+

foreach loops in archives.html and feed.xml:

*TODO*

diff --git a/html-gen.sh b/html-gen.sh index d66dc12..fb0f4d9 100644 --- a/html-gen.sh +++ b/html-gen.sh @@ -369,8 +369,10 @@ if [ $modification -gt 0 ]; then last_5_commits=`mktemp --suffix "-fugitive"` head -5 "$commits" > "$last_5_commits" cat "$templates_dir/feed.xml" | \ + replace_includes | \ replace_foreach "article" "$last_5_articles" | \ replace_foreach "commit" "$last_5_commits" | \ + replace_str "page_title" "feed" | \ replace_str "blog_url" "$blog_url" | \ replace_commit_info "-1" | \ sed "/^\s*$/d" > "$public_dir/feed.xml" -- cgit v1.2.3