Fair warning: This is all under development and not yet packaged up for easy deployment ## Cinera ### Download, and prepare the parser 1. `git clone git@gitssh.handmade.network:Annotation-Pushers/Annotation-System.git` 2. `cd Annotation-System/hmmlib` 3. `make` 4. `cp hmml.a hmmlib.h ../cinera/` 5. `cd ../cinera/` Note: For each parser update, remember to make and copy it into place. ### Install the dependency 1. curl ### Build 1. `$SHELL cinera.c` ### Configure the server If you enforce a strict Content Security Policy and X-Frame-Options in your server configuration as recommended by [Security Headers](https://securityheaders.com/), you may enable _Cinera_ to function by making two small tweaks: add_header Content-Security-Policy "default-src … https://www.youtube.com https://s.ytimg.com"; add_header X-Frame-Options "ALLOW-FROM https://www.youtube.com"; Note: For more information about these and other security headers, see Scott Helme's articles [Content Security Policy - An Introduction](https://scotthelme.co.uk/content-security-policy-an-introduction/) and [Hardening your HTTP response headers](https://scotthelme.co.uk/hardening-your-http-response-headers/#x-frame-options). ### Run #### Single Edition operation cinera test.hmml This simply generates an HTML file (and updates `cinera_topics.css` if needed) from `test.hmml` and outputs to `out.html` (configurable with -o). #### Project Edition operation cinera -p ProjectID Setting the ProjectID with the `-p` flag triggers Project Edition. In this edition _Cinera_ monitors the Project Input Directory for new, edited and deleted .hmml files, and generates one table of contents / search page and a player page each for valid sets of annotations (or removes them, if needed). 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) -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 -y Player Template Location, relative to Template Directory #### Templates *Index Template* - `` _the necessary `.css` and `.js` files_ - `` _the table of contents, and search functionality_ *Player Template* - `` _the necessary `.css` and `.js` files, and charset setting_ - `` _ _the menu bar that typically appears above the player in my samples_ - `` _the player_ - `` _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* - `` _the day / episode name, intended to be used inside your own `` 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_URL__ -->` _the URL where we have derived the page will be publically accessibly, 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_ Feel free to play with templates to your heart's content. If you do anything invalid, _Cinera_ will tell you what's wrong. Note: There is currently an issue sizing the annotation marker container if your HTML document contains `<!DOCTYPE html>`. To work around this for now, please do not declare a DOCTYPE and instead let the page be displayed in [quirks mode](https://www.w3.org/International/articles/serving-xhtml/#quirks). #### Arguments Usage: ./cinera [option(s)] filename(s) 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 ("") 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 -c <CSS directory path> Override default CSS directory (""), relative to root -i <images directory path> Override default images directory (""), relative to root -j <JS directory path> Override default JS directory (""), relative to root 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 -m <default medium> Override default default medium ("programming") Known project defaults: bitwise: programming book: research pcalc: programming riscy: programming chat: speech code: programming intro-to-c: programming misc: admin ray: programming hmdshow: speech lecture: speech stream: programming special: programming obbg: programming sysadmin: admin -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> Override default annotations directory (".") -t <templates directory> Override default templates directory (".") -x <index template location> Set index 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 to template directory, and enable integration Project Output Paths -b <base output directory> Override project's default base output directory (".") -B <base URL> 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 -a <player location> Override default player location (""), relative to base NOTE: The PlayerURLPrefix is currently hardcoded in cinera.c but will be configurable in the full configuration system Single Edition Output Path -o <output location> Override default output player location ("out.html") -e Display (examine) index file and exit -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 -w Force quote cache rebuild (memory aid: "wget") -l <n> Override default log level (0), where n is from 0 (terse) to 7 (verbose) -u <seconds> Override default update interval (4) -v Display version and exit -h Display this help