Commit 3da53413 authored by Matt Mascarenhas's avatar Matt Mascarenhas

cinera.c: Revved resources

Database version 4

Revving resources involves hashing asset files and appending a query
string to their URLs. Additionally we monitor asset files for changes
and edit their new checksum hash into all HTML files citing them.

This commit also introduces new template tags for assets (listed below)
with which you may instruct Cinera to rev assets of your choice. There
is further information about this in the help (-h) and the README.md

Amongst other minor changes, we now support unset $XDG_CACHE_HOME and
$HOME
    - Thanks to insofaras for wordexp()

New flags:
    -Q Set query string

New template tags:
    __CINERA_ASSET__
    __CINERA_CSS__
    __CINERA_IMAGE__
    __CINERA_JS__

Renamed template tag:
    __CINERA_SEARCH__ (was __CINERA_INDEX__)
parent 07db5d03
......@@ -3,6 +3,11 @@ deployment
## Cinera
### Install the dependencies
1. flex (for hmmlib)
2. curl (for cinera)
### Download, and prepare the parser
1. `git clone [email protected]:Annotation-Pushers/Annotation-System.git`
......@@ -13,10 +18,6 @@ deployment
Note: For each parser update, remember to make and copy it into place.
### Install the dependency
1. curl
### Build
1. `$SHELL cinera.c`
......@@ -57,56 +58,75 @@ By default all directories - input and output - are set to the current working
directory. Typical operation will involve setting these flags:
-d Project Input Directory, the directory where the .hmml files reside
-r Root Directory, path shallower than or equal to the CSS, Images and JS
directories
-R Root URL, corresponding to the Root Directory (optional if the Output
Base Directory resides in the Root Directory)
-r Asset Root Directory, path shallower than or equal to the CSS, Images and
JS directories
-R Asset Root URL, corresponding to the Root Directory
-c CSS Directory, relative to Root
-i Images Directory, relative to Root
-j JS Directory, relative to Root
-b Output Base Directory, location of the table of contents / search page
-B Output Base URL, corresponding to the Output Base Directory
-t Template Directory
-x Index Template Location, relative to Template Directory
-x Search Template Location, relative to Template Directory
-y Player Template Location, relative to Template Directory
#### Templates
*Index Template*
- `<!-- __CINERA_INCLUDES__ -->` _the necessary `.css` and `.js` files_
- `<!-- __CINERA_INDEX__ -->` _the table of contents, and search functionality_
*Search Template*
- `<!-- __CINERA_INCLUDES__ -->` _to put inside your own `<head></head>`_
- `<!-- __CINERA_SEARCH__ -->` _the table of contents and search functionality_
*Player Template*
- `<!-- __CINERA_INCLUDES__ -->` _the necessary `.css` and `.js` files, and
charset setting_
- `<!-- __CINERA_MENUS__ -->` _ _the menu bar that typically appears above the
player in my samples_
- `<!-- __CINERA_PLAYER__ -->` _the player_
- `<!-- __CINERA_SCRIPT__ -->` _the filter state objects and `.js` file, which
must come after both the MENUS and PLAYER tags_
- `<!-- __CINERA_INCLUDES__ -->` _to put inside your own `<head></head>`_
- `<!-- __CINERA_MENUS__ -->`
- `<!-- __CINERA_PLAYER__ -->`
- `<!-- __CINERA_SCRIPT__ -->` _must come after `<!-- __CINERA_MENUS__ -->` and `<!-- __CINERA_PLAYER__ -->`_
*Optional tags available for use in your Player Template*
- `<!-- __CINERA_TITLE__ -->` _the day / episode name, intended to be used
inside your own `<title>` element, but may be used wherever and as many times
as you want on your page_
- `<!-- __CINERA_VIDEO_ID__ -->` _the unique identifer of the video as provided
by the VoD platform_
*Other available tags*
- `<!-- __CINERA_PROJECT__ -->` _the full name of the project_
- `<!-- __CINERA_PROJECT_ID__ -->` _the ID of the project_
- `<!-- __CINERA_THEME__ -->` _the theme of the project_
- `<!-- __CINERA_URL__ -->` _the URL where we have derived the page will be
publically accessibly, only really usable if BaseURL is set (-B)_
- `<!-- __CINERA_TITLE__ -->`
- `<!-- __CINERA_VIDEO_ID__ -->`
*Other tags available for use in either template*
- Asset tags:
- `<!-- __CINERA_ASSET__ path.ext -->`
General purpose tag that outputs the URL of the specified asset
relative to the Asset Root URL (-R)
- `<!-- __CINERA_IMAGE__ path.ext -->`
General purpose tag that outputs the URL of the specified asset
relative to the Images Directory (-i)
- `<!-- __CINERA_CSS__ path.ext -->`
Convenience tag that outputs a <link rel="stylesheet"...> node
for the specified asset relative to the CSS Directory (-c), for
use inside your <head> block
- `<!-- __CINERA_JS__ path.ext -->`
Convenience tag that outputs a <script type="text/javascript"...>
node for the specified asset relative to the JS Directory (-j),
for use wherever a <script> node is valid
The path.ext in these tags supports parent directories to locate the
asset file relative to its specified type directory (generic, CSS, image
or JS), including the "../" directory, and paths containing spaces must
be surrounded with double-quotes (\-escapable if the quoted path itself
contains double-quotes).
All these asset tags additionally perform revving, appending a query
string (-Q) and the file's checksum to the URL. Changes to a file
trigger a rehash and edit of all HTML pages citing this asset.
- `<!-- __CINERA_PROJECT__ -->`
- `<!-- __CINERA_PROJECT_ID__ -->`
- `<!-- __CINERA_THEME__ -->`
- `<!-- __CINERA_URL__ -->` _Only really usable if BaseURL is set (-B)_
- `<!-- __CINERA_CUSTOM0__ -->`
- `<!-- __CINERA_CUSTOM1__ -->`
- `<!-- __CINERA_CUSTOM2__ -->`
-
- `<!-- __CINERA_CUSTOM15__ -->`
_Freeform buffers for small snippets of localised information, e.g. a single
`<a>` element or perhaps a `<!-- comment -->` They correspond to the custom0
to custom15 attributes in the [video] node in your .hmml files 0 to 11 may
hold up to 255 characters 12 to 15 may hold up to 1023 characters_
Freeform buffers for small snippets of localised information, e.g. a
single `<a>` element or perhaps a `<!-- comment -->`
They correspond to the custom0 to custom15 attributes in the [video]
node in your .hmml files
0 to 11 may hold up to 255 characters
12 to 15 may hold up to 1023 characters
Feel free to play with templates to your heart's content. If you do anything
invalid, _Cinera_ will tell you what's wrong.
......@@ -117,10 +137,10 @@ invalid, _Cinera_ will tell you what's wrong.
Options:
Paths: (advisedly universal, but may be set per-(sub)project as required)
-r <root directory>
Override default root directory (".")
-R <root URL>
Override default root URL ("")
-r <assets root directory>
Override default assets root directory (".")
-R <assets root URL>
Override default assets root URL ("")
IMPORTANT: -r and -R must correspond to the same location
UNSUPPORTED: If you move files from RootDir, the RootURL should
correspond to the resulting location
......@@ -131,18 +151,22 @@ invalid, _Cinera_ will tell you what's wrong.
Override default images directory (""), relative to root
-j <JS directory path>
Override default JS directory (""), relative to root
-Q <revved resources query string>
Override default query string ("r")
To disable revved resources, set an empty string with -Q ""
Project Settings:
-p <project ID>
Set the project ID, equal to the "project" field in the HMML files
NOTE: Setting the project ID triggers PROJECT EDITION
Set the project ID, triggering PROJECT EDITION
-m <default medium>
Override default default medium ("programming")
Known project defaults:
bitwise: programming
book: research
pcalc: programming
coad: research
reader: research
riscy: programming
risc: speech
chat: speech
code: programming
intro-to-c: programming
......@@ -157,9 +181,6 @@ invalid, _Cinera_ will tell you what's wrong.
-s <style>
Set the style / theme, corresponding to a cinera__*.css file
This is equal to the "project" field in the HMML files by default
-q
Quit after syncing with annotation files in project input directory
UNSUPPORTED: This is likely to be removed in the future
Project Input Paths
-d <annotations directory>
......@@ -167,8 +188,8 @@ invalid, _Cinera_ will tell you what's wrong.
-t <templates directory>
Override default templates directory (".")
-x <index template location>
Set index template file path, either absolute or relative to
-x <search template location>
Set search template file path, either absolute or relative to
template directory, and enable integration
-y <player template location>
Set player template file path, either absolute or relative
......@@ -181,8 +202,8 @@ invalid, _Cinera_ will tell you what's wrong.
Override default base URL ("")
NOTE: This must be set, if -n or -a are to be used
-n <index location>
Override default index location (""), relative to base
-n <search location>
Override default search location (""), relative to base
-a <player location>
Override default player location (""), relative to base
NOTE: The PlayerURLPrefix is currently hardcoded in cinera.c but
......@@ -192,14 +213,18 @@ invalid, _Cinera_ will tell you what's wrong.
-o <output location>
Override default output player location ("out.html")
-e
Display (examine) index file and exit
-1
Open search result links in the same browser tab
NOTE: Ideal for a guide embedded in an iframe
-f
Force integration with an incomplete template
-g
Ignore video privacy status
NOTE: For use with projects whose videos are known to all be public,
to save us having to check their privacy status
-q
Quit after syncing with annotation files in project input directory
UNSUPPORTED: This is likely to be removed in the future
-w
Force quote cache rebuild (memory aid: "wget")
......@@ -207,6 +232,9 @@ invalid, _Cinera_ will tell you what's wrong.
Override default log level (0), where n is from 0 (terse) to 7 (verbose)
-u <seconds>
Override default update interval (4)
-e
Display (examine) database and exit
-v
Display version and exit
-h
......
This source diff could not be displayed because it is too large. You can view the blob instead.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment