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 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
    -u Root URL, corresponding to the Root Directory (optional if the Output
       Base Directory resides in the Root Directory)
    -b Output Base Directory, location of the table of contents / search page
	-t Player Template Location
	-x Index Template Location

#### Integration

    CINERA_MODE=INTEGRATE cinera test.hmml

This will integrate into `template_player.html` (configurable with -t) the
player and related elements generated from `test.hmml` and output to
`out_integrated.html`

Feel free to play with `template_player.html` to your heart's content. If you do
anything invalid, `cinera` will tell you what's wrong

#### Templates

Valid tags:

- `<!-- __CINERA_PROJECT__ -->` _the project's full name_
- `<!-- __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_

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

#### Arguments

	Usage: ./cinera [option(s)] filename(s)

	Options:
	    Paths:
	        -r <root directory>
	            Override default root directory (".")
	        -u <root URL>
	            Override default root URL ("")
	        -b <base output directory>
	            Override project's default base output directory (".")
	        -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
	        -t <player template location>
	            Override default player template location ("template_player.html"), relative to root
	            and automatically enable integration
	        -x <index template location>
	            Override default index template location ("template_index.html"), relative to root
	            and automatically enable integration
	
	        -o <output location>
	            Override default output player location for SINGLE_EDITION ("out.html")
	        -d <project directory>
	            Override default project directory (".")
	
	    -f
	        Force integration with an incomplete template
	    -p <project ID>
	        Set the project ID, corresponding to the "project" field in the HMML files
        -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
	    -l <n>
	        Override default log level (0), where n is from 0 (terse) to 7 (verbose)
	    -m <default medium>
	        Override default default medium ("programming")
	    -U <seconds>
	        Override default update interval ("4")
        -v
            display version and exit
	    -h
	        display this help

#### Environment Variables

	CINERA_MODE=INTEGRATE
		Enable integration