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__)
This commit is contained in:
Matt Mascarenhas 2018-09-17 19:06:31 +01:00
parent 07db5d0397
commit 3da53413ce
2 changed files with 4175 additions and 1783 deletions

130
README.md
View File

@ -3,6 +3,11 @@ deployment
## Cinera ## Cinera
### Install the dependencies
1. flex (for hmmlib)
2. curl (for cinera)
### Download, and prepare the parser ### Download, and prepare the parser
1. `git clone git@gitssh.handmade.network:Annotation-Pushers/Annotation-System.git` 1. `git clone git@gitssh.handmade.network:Annotation-Pushers/Annotation-System.git`
@ -13,10 +18,6 @@ deployment
Note: For each parser update, remember to make and copy it into place. Note: For each parser update, remember to make and copy it into place.
### Install the dependency
1. curl
### Build ### Build
1. `$SHELL cinera.c` 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: directory. Typical operation will involve setting these flags:
-d Project Input Directory, the directory where the .hmml files reside -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 -r Asset Root Directory, path shallower than or equal to the CSS, Images and
directories JS directories
-R Root URL, corresponding to the Root Directory (optional if the Output -R Asset Root URL, corresponding to the Root Directory
Base Directory resides in the Root Directory)
-c CSS Directory, relative to Root -c CSS Directory, relative to Root
-i Images Directory, relative to Root -i Images Directory, relative to Root
-j JS 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 Directory, location of the table of contents / search page
-B Output Base URL, corresponding to the Output Base Directory -B Output Base URL, corresponding to the Output Base Directory
-t Template 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 -y Player Template Location, relative to Template Directory
#### Templates #### Templates
*Index Template* *Search Template*
- `<!-- __CINERA_INCLUDES__ -->` _the necessary `.css` and `.js` files_ - `<!-- __CINERA_INCLUDES__ -->` _to put inside your own `<head></head>`_
- `<!-- __CINERA_INDEX__ -->` _the table of contents, and search functionality_ - `<!-- __CINERA_SEARCH__ -->` _the table of contents and search functionality_
*Player Template* *Player Template*
- `<!-- __CINERA_INCLUDES__ -->` _the necessary `.css` and `.js` files, and - `<!-- __CINERA_INCLUDES__ -->` _to put inside your own `<head></head>`_
charset setting_ - `<!-- __CINERA_MENUS__ -->`
- `<!-- __CINERA_MENUS__ -->` _ _the menu bar that typically appears above the - `<!-- __CINERA_PLAYER__ -->`
player in my samples_ - `<!-- __CINERA_SCRIPT__ -->` _must come after `<!-- __CINERA_MENUS__ -->` and `<!-- __CINERA_PLAYER__ -->`_
- `<!-- __CINERA_PLAYER__ -->` _the player_
- `<!-- __CINERA_SCRIPT__ -->` _the filter state objects and `.js` file, which
must come after both the MENUS and PLAYER tags_
*Optional tags available for use in your Player Template* *Optional tags available for use in your Player Template*
- `<!-- __CINERA_TITLE__ -->` _the day / episode name, intended to be used - `<!-- __CINERA_TITLE__ -->`
inside your own `<title>` element, but may be used wherever and as many times - `<!-- __CINERA_VIDEO_ID__ -->`
as you want on your page_
- `<!-- __CINERA_VIDEO_ID__ -->` _the unique identifer of the video as provided
by the VoD platform_
*Other available tags* *Other tags available for use in either template*
- `<!-- __CINERA_PROJECT__ -->` _the full name of the project_ - Asset tags:
- `<!-- __CINERA_PROJECT_ID__ -->` _the ID of the project_ - `<!-- __CINERA_ASSET__ path.ext -->`
- `<!-- __CINERA_THEME__ -->` _the theme of the project_ General purpose tag that outputs the URL of the specified asset
- `<!-- __CINERA_URL__ -->` _the URL where we have derived the page will be relative to the Asset Root URL (-R)
publically accessibly, only really usable if BaseURL is set (-B)_ - `<!-- __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_CUSTOM0__ -->`
- `<!-- __CINERA_CUSTOM1__ -->` - `<!-- __CINERA_CUSTOM1__ -->`
- `<!-- __CINERA_CUSTOM2__ -->` - `<!-- __CINERA_CUSTOM2__ -->`
- ⋮
- `<!-- __CINERA_CUSTOM15__ -->` - `<!-- __CINERA_CUSTOM15__ -->`
_Freeform buffers for small snippets of localised information, e.g. a single Freeform buffers for small snippets of localised information, e.g. a
`<a>` element or perhaps a `<!-- comment -->` They correspond to the custom0 single `<a>` element or perhaps a `<!-- comment -->`
to custom15 attributes in the [video] node in your .hmml files 0 to 11 may They correspond to the custom0 to custom15 attributes in the [video]
hold up to 255 characters 12 to 15 may hold up to 1023 characters_ 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 Feel free to play with templates to your heart's content. If you do anything
invalid, _Cinera_ will tell you what's wrong. invalid, _Cinera_ will tell you what's wrong.
@ -117,10 +137,10 @@ invalid, _Cinera_ will tell you what's wrong.
Options: Options:
Paths: (advisedly universal, but may be set per-(sub)project as required) Paths: (advisedly universal, but may be set per-(sub)project as required)
-r <root directory> -r <assets root directory>
Override default root directory (".") Override default assets root directory (".")
-R <root URL> -R <assets root URL>
Override default root URL ("") Override default assets root URL ("")
IMPORTANT: -r and -R must correspond to the same location IMPORTANT: -r and -R must correspond to the same location
UNSUPPORTED: If you move files from RootDir, the RootURL should UNSUPPORTED: If you move files from RootDir, the RootURL should
correspond to the resulting location correspond to the resulting location
@ -131,18 +151,22 @@ invalid, _Cinera_ will tell you what's wrong.
Override default images directory (""), relative to root Override default images directory (""), relative to root
-j <JS directory path> -j <JS directory path>
Override default JS directory (""), relative to root 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: Project Settings:
-p <project ID> -p <project ID>
Set the project ID, equal to the "project" field in the HMML files Set the project ID, triggering PROJECT EDITION
NOTE: Setting the project ID triggers PROJECT EDITION
-m <default medium> -m <default medium>
Override default default medium ("programming") Override default default medium ("programming")
Known project defaults: Known project defaults:
bitwise: programming bitwise: programming
book: research book: research
pcalc: programming coad: research
reader: research
riscy: programming riscy: programming
risc: speech
chat: speech chat: speech
code: programming code: programming
intro-to-c: programming intro-to-c: programming
@ -157,9 +181,6 @@ invalid, _Cinera_ will tell you what's wrong.
-s <style> -s <style>
Set the style / theme, corresponding to a cinera__*.css file Set the style / theme, corresponding to a cinera__*.css file
This is equal to the "project" field in the HMML files by default 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 Project Input Paths
-d <annotations directory> -d <annotations directory>
@ -167,8 +188,8 @@ invalid, _Cinera_ will tell you what's wrong.
-t <templates directory> -t <templates directory>
Override default templates directory (".") Override default templates directory (".")
-x <index template location> -x <search template location>
Set index template file path, either absolute or relative to Set search template file path, either absolute or relative to
template directory, and enable integration template directory, and enable integration
-y <player template location> -y <player template location>
Set player template file path, either absolute or relative 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 ("") Override default base URL ("")
NOTE: This must be set, if -n or -a are to be used NOTE: This must be set, if -n or -a are to be used
-n <index location> -n <search location>
Override default index location (""), relative to base Override default search location (""), relative to base
-a <player location> -a <player location>
Override default player location (""), relative to base Override default player location (""), relative to base
NOTE: The PlayerURLPrefix is currently hardcoded in cinera.c but 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> -o <output location>
Override default output player location ("out.html") Override default output player location ("out.html")
-e -1
Display (examine) index file and exit Open search result links in the same browser tab
NOTE: Ideal for a guide embedded in an iframe
-f -f
Force integration with an incomplete template Force integration with an incomplete template
-g -g
Ignore video privacy status Ignore video privacy status
NOTE: For use with projects whose videos are known to all be public, NOTE: For use with projects whose videos are known to all be public,
to save us having to check their privacy status 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 -w
Force quote cache rebuild (memory aid: "wget") 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) Override default log level (0), where n is from 0 (terse) to 7 (verbose)
-u <seconds> -u <seconds>
Override default update interval (4) Override default update interval (4)
-e
Display (examine) database and exit
-v -v
Display version and exit Display version and exit
-h -h

File diff suppressed because it is too large Load Diff