README.md 9.78 KB
Newer Older
1 2
Fair warning: This is all under development and not yet packaged up for easy
deployment
3

4
## Cinera
5

6 7 8 9 10
### Install the dependencies

1. flex (for hmmlib)
2. curl (for cinera)

11
### Download, and prepare the parser
12

13 14 15
1. `git clone [email protected]:Annotation-Pushers/Annotation-System.git`
2. `cd Annotation-System/hmmlib`
3. `make`
Matt Mascarenhas committed
16 17
4. `cp hmml.a hmmlib.h ../cinera/`
5. `cd ../cinera/`
18

19
Note: For each parser update, remember to make and copy it into place.
20

21
### Build
22

23
1. `$SHELL cinera.c`
24

25 26 27 28 29 30 31 32 33 34 35 36 37 38
### 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).

39 40
### Run

Matt Mascarenhas committed
41
#### Single Edition operation
42

Matt Mascarenhas committed
43
    cinera test.hmml
44 45

This simply generates an HTML file (and updates `cinera_topics.css` if needed)
46
from `test.hmml` and outputs to `out.html` (configurable with -o).
47

Matt Mascarenhas committed
48
#### Project Edition operation
49

Matt Mascarenhas committed
50
    cinera -p ProjectID
51

Matt Mascarenhas committed
52
Setting the ProjectID with the `-p` flag triggers Project Edition. In this
53
edition _Cinera_ monitors the Project Input Directory for new, edited and
Matt Mascarenhas committed
54 55
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).
56

Matt Mascarenhas committed
57 58 59 60
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
61 62 63
    -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
64 65 66
    -c CSS Directory, relative to Root
    -i Images Directory, relative to Root
    -j JS Directory, relative to Root
Matt Mascarenhas committed
67
    -b Output Base Directory, location of the table of contents / search page
68 69
    -B Output Base URL, corresponding to the Output Base Directory
    -t Template Directory
70
    -x Search Template Location, relative to Template Directory
71
    -y Player Template Location, relative to Template Directory
72

Matt Mascarenhas committed
73
#### Templates
74

75 76 77
*Search Template*
- `<!-- __CINERA_INCLUDES__ -->` _to put inside your own `<head></head>`_
- `<!-- __CINERA_SEARCH__ -->` _the table of contents and search functionality_
Matt Mascarenhas committed
78 79

*Player Template*
80 81 82 83
- `<!-- __CINERA_INCLUDES__ -->` _to put inside your own `<head></head>`_
- `<!-- __CINERA_MENUS__ -->`
- `<!-- __CINERA_PLAYER__ -->`
- `<!-- __CINERA_SCRIPT__ -->` _must come after `<!-- __CINERA_MENUS__ -->` and `<!-- __CINERA_PLAYER__ -->`_
84 85

*Optional tags available for use in your Player Template*
86 87
- `<!-- __CINERA_TITLE__ -->`
- `<!-- __CINERA_VIDEO_ID__ -->`
88
- `<!-- __CINERA_VOD_PLATFORM__ -->`
89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117

*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__ -->`
118
- `<!-- __CINERA_SEARCH_URL__ -->`
119 120
- `<!-- __CINERA_THEME__ -->`
- `<!-- __CINERA_URL__ -->` _Only really usable if BaseURL is set (-B)_
121 122 123
- `<!-- __CINERA_CUSTOM0__ -->`
- `<!-- __CINERA_CUSTOM1__ -->`
- `<!-- __CINERA_CUSTOM2__ -->`
124

125
- `<!-- __CINERA_CUSTOM15__ -->`
126 127 128 129 130 131
   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
132 133

Feel free to play with templates to your heart's content. If you do anything
134 135
invalid, _Cinera_ will tell you what's wrong.

136 137
#### Arguments

138 139 140 141
    Usage: ./cinera [option(s)] filename(s)

    Options:
        Paths: (advisedly universal, but may be set per-(sub)project as required)
142 143 144 145
            -r <assets root directory>
                Override default assets root directory (".")
            -R <assets root URL>
                Override default assets root URL ("")
146 147 148 149 150 151 152 153 154 155
                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
156 157 158
                -Q <revved resources query string>
                    Override default query string ("r")
                    To disable revved resources, set an empty string with -Q ""
159 160 161

        Project Settings:
            -p <project ID>
162
                Set the project ID, triggering PROJECT EDITION
163 164 165
            -m <default medium>
                Override default default medium ("programming")
                Known project defaults:
166
                    bitwise:        programming
167
                    book:           research
168 169
                    coad:           research
                    reader:         research
170
                    riscy:          programming
171
                    risc:           speech
172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192
                    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 (".")

193 194
                -x <search template location>
                    Set search template file path, either absolute or relative to
195 196 197 198 199 200 201 202 203 204 205 206
                    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

207 208
                -n <search location>
                    Override default search location (""), relative to base
209 210 211 212 213 214 215 216 217
                -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")

218 219 220
        -1
            Open search result links in the same browser tab
                NOTE: Ideal for a guide embedded in an iframe
221 222
        -f
            Force integration with an incomplete template
223 224 225 226
        -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
227 228 229
        -q
            Quit after syncing with annotation files in project input directory
            UNSUPPORTED: This is likely to be removed in the future
230 231 232 233 234 235 236
        -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)
237 238 239

        -e
            Display (examine) database and exit
240
        -v
241 242 243
            Display version and exit
        -h
            Display this help