githubhjs / fsbuilder

falling-sky processor that reads templates and translations, outputs compiled publishable content

Builder

Go based template compiler for falling-sky

This is being built as a replacement to falling-sky's build.pl, which has a large number of dependencies.

Index

• Builder
  • Index
  • Templates
  • Includes
  • Translations
• Installation
  • Prerequisites
  • Configuration

About

This tool will do several things:

• Read translations/falling-sky.pot for the existing database of translation strings
• Read translations/dl/*/*.po for translations provided by translators (and downloaded from CrowdIn)
• Read templates/js for top-level .js files
• Read templates/css for top-level .css files
• Read templates/html for top-level .html files
• Read templates/php for top-level .php files
• Read templates/apache for top-level .htaccess and .example files
• Read images/ for .gif .png .jpg and .jpeg files

For outputs, this will create one directory called output/.

• output/ contains js, css, html, php files, plus some apache files
• output/images contains images, plus one .htacces file
• ouputt/images-nc contains the same images, plus a different .htaccess file

Templates

These are the real sources for the falling-sky project; aka test-ipv6.com (and mirror sites).

Thes are processed by Go's template engine. For the template engine we use [% and %] as markers.

These variables are defined:

[% $page %] - Base page name with full text. This is defined inside the .html files specifically, and used by header.inc and navigation includes to selectively enable and disable features/outputs. A typical usage will be to assign the page name at the top - such as: [% $page := "6to4" %].

[% .Baasename %] - Base page name (used in the filename). Example would be simply "index". Defined before template expansion.

[% .GitInfo.Repository %] - Git repo info for the current directory.

[% .GitInfo.Version %] - A synthetic version number based on the latest git tags, and log count. Update the tags to increment the major/minor version numbers.

[% .GitInfo.Date] - UTC time that the last Git commit was made.

[% .DirSignature %] - A signature string that includes the .GitInfo.Version as well as a md5 hash of the most important bits of Apache configuration. The md5 hash will remain constant unless languages are added, or the Apache templates change.

Includes

These directives are also defined, but with strict limitations.

[% PROCESS "filename.inc" %] will replace the [%..%] with the contents of filename.inc. This gives us the ability to have include files; to break things into reusable parts. Some of the web pages, for example, reuse content across various FAQ pages.

Translations

We are doing translations just outside of the template engine. We do this partially for speed (the same template output can be used for all langauges); but also to make it simpler to edit.

Text that is to be translated is simply wrapped around double curly braces, like these examples:

  x = "{{JavaScript text to be translated}}"

<span>{{HTML text to be translated}}</span>

The use of {{ and }} should be safe for text editors that offer syntax checking and highlighting.

Installation

Prerequisites

Building this application requires Go. This has been tested with Go 1.6.

This tool could make use of third party tools to optimize output. These tools include: uglify-js2, cssmin, (html) tidy. At this time their gains are not adequate for what they cost is both in time and browser obfuscation.

If we were to use those, we would use those in post-processing. If the project does encourage post-processing again, we will document the post-processing commands. For now those remain dormant.

Building

#Make sure `GOPATH` is set in your environment.
echo $GOPATH
cd $GOPATH
mkdir -p $GOPATH/src/github.com/falling-sky
cd $GOPATH/src/github.com/falling-sky
git clone [email protected]:falling-sky/builder.git
cd builder 
go build
cp builder /path/to/falling-sky/source/

Shortcut from falling-sky source code

You might find it easier to use make builder from the falling-sky source directory. This will automatically set up a GOPATH for you, clone the source, and build the binary.

Configuration

The build tool does support a config file. Run this to get a template:

builder --example > builder.conf

And then, after editing the configuration..

builder --config builder.conf