Annotation-System/README.md

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, 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 and Hardening your HTTP response headers.

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

• <!-- __CINERA_INCLUDES__ --> the necessary .css and .js files
• <!-- __CINERA_INDEX__ --> 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

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_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.

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