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](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*
- `<!-- __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