2017-06-22 22:11:01 +00:00
|
|
|
Fair warning: This is all under development and not yet packaged up for easy
|
|
|
|
|
deployment
|
2017-06-21 21:23:21 +00:00
|
|
|
|
2017-11-18 00:27:33 +00:00
|
|
|
## Cinera
|
2017-06-21 21:23:21 +00:00
|
|
|
|
2018-09-17 18:06:31 +00:00
|
|
|
### Install the dependencies
|
|
|
|
|
|
|
|
|
|
1. flex (for hmmlib)
|
|
|
|
|
2. curl (for cinera)
|
|
|
|
|
|
2017-07-24 23:43:26 +00:00
|
|
|
### Download, and prepare the parser
|
2017-06-21 21:23:21 +00:00
|
|
|
|
2017-07-24 23:43:26 +00:00
|
|
|
1. `git clone git@gitssh.handmade.network:Annotation-Pushers/Annotation-System.git`
|
|
|
|
|
2. `cd Annotation-System/hmmlib`
|
|
|
|
|
3. `make`
|
2017-11-11 00:34:47 +00:00
|
|
|
4. `cp hmml.a hmmlib.h ../cinera/`
|
|
|
|
|
5. `cd ../cinera/`
|
2017-06-21 21:27:57 +00:00
|
|
|
|
2018-05-01 21:05:44 +00:00
|
|
|
Note: For each parser update, remember to make and copy it into place.
|
2017-06-21 21:23:21 +00:00
|
|
|
|
2017-07-24 23:43:26 +00:00
|
|
|
### Build
|
2017-06-21 21:23:21 +00:00
|
|
|
|
2017-11-18 00:27:33 +00:00
|
|
|
1. `$SHELL cinera.c`
|
2017-06-21 21:23:21 +00:00
|
|
|
|
2018-05-01 21:05:44 +00:00
|
|
|
### 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).
|
|
|
|
|
|
2017-06-21 21:23:21 +00:00
|
|
|
### Run
|
|
|
|
|
|
2017-11-11 00:34:47 +00:00
|
|
|
#### Single Edition operation
|
2017-06-21 21:23:21 +00:00
|
|
|
|
2017-11-11 00:34:47 +00:00
|
|
|
cinera test.hmml
|
2017-06-21 21:23:21 +00:00
|
|
|
|
|
|
|
|
This simply generates an HTML file (and updates `cinera_topics.css` if needed)
|
2018-05-01 21:05:44 +00:00
|
|
|
from `test.hmml` and outputs to `out.html` (configurable with -o).
|
2017-06-21 21:23:21 +00:00
|
|
|
|
2017-11-11 00:34:47 +00:00
|
|
|
#### Project Edition operation
|
2017-06-21 21:23:21 +00:00
|
|
|
|
2017-11-11 00:34:47 +00:00
|
|
|
cinera -p ProjectID
|
2017-06-21 21:23:21 +00:00
|
|
|
|
2017-11-11 00:34:47 +00:00
|
|
|
Setting the ProjectID with the `-p` flag triggers Project Edition. In this
|
2018-05-01 21:05:44 +00:00
|
|
|
edition _Cinera_ monitors the Project Input Directory for new, edited and
|
2017-11-11 00:34:47 +00:00
|
|
|
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).
|
2017-06-21 21:23:21 +00:00
|
|
|
|
2017-11-11 00:34:47 +00:00
|
|
|
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
|
2018-09-17 18:06:31 +00:00
|
|
|
-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
|
2018-02-28 01:04:06 +00:00
|
|
|
-c CSS Directory, relative to Root
|
|
|
|
|
-i Images Directory, relative to Root
|
|
|
|
|
-j JS Directory, relative to Root
|
2017-11-11 00:34:47 +00:00
|
|
|
-b Output Base Directory, location of the table of contents / search page
|
2018-02-28 01:04:06 +00:00
|
|
|
-B Output Base URL, corresponding to the Output Base Directory
|
|
|
|
|
-t Template Directory
|
2018-09-17 18:06:31 +00:00
|
|
|
-x Search Template Location, relative to Template Directory
|
2018-02-28 01:04:06 +00:00
|
|
|
-y Player Template Location, relative to Template Directory
|
2017-06-21 21:23:21 +00:00
|
|
|
|
2017-11-11 00:34:47 +00:00
|
|
|
#### Templates
|
2017-06-21 21:23:21 +00:00
|
|
|
|
2018-09-17 18:06:31 +00:00
|
|
|
*Search Template*
|
|
|
|
|
- `<!-- __CINERA_INCLUDES__ -->` _to put inside your own `<head></head>`_
|
|
|
|
|
- `<!-- __CINERA_SEARCH__ -->` _the table of contents and search functionality_
|
2017-11-11 00:34:47 +00:00
|
|
|
|
|
|
|
|
*Player Template*
|
2018-09-17 18:06:31 +00:00
|
|
|
- `<!-- __CINERA_INCLUDES__ -->` _to put inside your own `<head></head>`_
|
|
|
|
|
- `<!-- __CINERA_MENUS__ -->`
|
|
|
|
|
- `<!-- __CINERA_PLAYER__ -->`
|
|
|
|
|
- `<!-- __CINERA_SCRIPT__ -->` _must come after `<!-- __CINERA_MENUS__ -->` and `<!-- __CINERA_PLAYER__ -->`_
|
2018-02-28 01:04:06 +00:00
|
|
|
|
|
|
|
|
*Optional tags available for use in your Player Template*
|
2018-09-17 18:06:31 +00:00
|
|
|
- `<!-- __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)_
|
2018-02-28 01:04:06 +00:00
|
|
|
- `<!-- __CINERA_CUSTOM0__ -->`
|
|
|
|
|
- `<!-- __CINERA_CUSTOM1__ -->`
|
|
|
|
|
- `<!-- __CINERA_CUSTOM2__ -->`
|
2018-09-17 18:06:31 +00:00
|
|
|
⋮
|
2018-02-28 01:04:06 +00:00
|
|
|
- `<!-- __CINERA_CUSTOM15__ -->`
|
2018-09-17 18:06:31 +00:00
|
|
|
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
|
2018-02-28 01:04:06 +00:00
|
|
|
|
|
|
|
|
Feel free to play with templates to your heart's content. If you do anything
|
2018-05-01 21:05:44 +00:00
|
|
|
invalid, _Cinera_ will tell you what's wrong.
|
|
|
|
|
|
2017-06-28 14:23:55 +00:00
|
|
|
#### Arguments
|
|
|
|
|
|
2018-02-28 01:04:06 +00:00
|
|
|
Usage: ./cinera [option(s)] filename(s)
|
|
|
|
|
|
|
|
|
|
Options:
|
|
|
|
|
Paths: (advisedly universal, but may be set per-(sub)project as required)
|
2018-09-17 18:06:31 +00:00
|
|
|
-r <assets root directory>
|
|
|
|
|
Override default assets root directory (".")
|
|
|
|
|
-R <assets root URL>
|
|
|
|
|
Override default assets root URL ("")
|
2018-02-28 01:04:06 +00:00
|
|
|
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
|
2018-09-17 18:06:31 +00:00
|
|
|
-Q <revved resources query string>
|
|
|
|
|
Override default query string ("r")
|
|
|
|
|
To disable revved resources, set an empty string with -Q ""
|
2018-02-28 01:04:06 +00:00
|
|
|
|
|
|
|
|
Project Settings:
|
|
|
|
|
-p <project ID>
|
2018-09-17 18:06:31 +00:00
|
|
|
Set the project ID, triggering PROJECT EDITION
|
2018-02-28 01:04:06 +00:00
|
|
|
-m <default medium>
|
|
|
|
|
Override default default medium ("programming")
|
|
|
|
|
Known project defaults:
|
2018-05-01 21:05:44 +00:00
|
|
|
bitwise: programming
|
2018-02-28 01:04:06 +00:00
|
|
|
book: research
|
2018-09-17 18:06:31 +00:00
|
|
|
coad: research
|
|
|
|
|
reader: research
|
2018-02-28 01:04:06 +00:00
|
|
|
riscy: programming
|
2018-09-17 18:06:31 +00:00
|
|
|
risc: speech
|
2018-02-28 01:04:06 +00:00
|
|
|
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
|
|
|
|
|
|
|
|
|
|
Project Input Paths
|
|
|
|
|
-d <annotations directory>
|
|
|
|
|
Override default annotations directory (".")
|
|
|
|
|
-t <templates directory>
|
|
|
|
|
Override default templates directory (".")
|
|
|
|
|
|
2018-09-17 18:06:31 +00:00
|
|
|
-x <search template location>
|
|
|
|
|
Set search template file path, either absolute or relative to
|
2018-02-28 01:04:06 +00:00
|
|
|
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
|
|
|
|
|
|
2018-09-17 18:06:31 +00:00
|
|
|
-n <search location>
|
|
|
|
|
Override default search location (""), relative to base
|
2018-02-28 01:04:06 +00:00
|
|
|
-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")
|
|
|
|
|
|
2018-09-17 18:06:31 +00:00
|
|
|
-1
|
|
|
|
|
Open search result links in the same browser tab
|
|
|
|
|
NOTE: Ideal for a guide embedded in an iframe
|
2018-02-28 01:04:06 +00:00
|
|
|
-f
|
|
|
|
|
Force integration with an incomplete template
|
2018-05-01 21:05:44 +00:00
|
|
|
-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
|
2018-09-17 18:06:31 +00:00
|
|
|
-q
|
|
|
|
|
Quit after syncing with annotation files in project input directory
|
|
|
|
|
UNSUPPORTED: This is likely to be removed in the future
|
2018-02-28 01:04:06 +00:00
|
|
|
-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)
|
2018-09-17 18:06:31 +00:00
|
|
|
|
|
|
|
|
-e
|
|
|
|
|
Display (examine) database and exit
|
2017-11-18 01:02:49 +00:00
|
|
|
-v
|
2018-02-28 01:04:06 +00:00
|
|
|
Display version and exit
|
|
|
|
|
-h
|
|
|
|
|
Display this help
|
