Annotation-System/README.md

193 lines
7.5 KiB
Markdown

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 Dependencies
1. curl
### Build
1. `$SHELL cinera.c`
### 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`
#### 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_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:
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
-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