README.md 7.63 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
### Download, and prepare the parser
7

8 9 10
1. `git clone [email protected]:Annotation-Pushers/Annotation-System.git`
2. `cd Annotation-System/hmmlib`
3. `make`
Matt Mascarenhas's avatar
Matt Mascarenhas committed
11 12
4. `cp hmml.a hmmlib.h ../cinera/`
5. `cd ../cinera/`
13

14
Note: For each parser update, remember to make and copy it into place
15

16 17 18 19
### Install Dependencies

1. curl

20
### Build
21

22
1. `$SHELL cinera.c`
23 24 25

### Run

Matt Mascarenhas's avatar
Matt Mascarenhas committed
26
#### Single Edition operation
27

Matt Mascarenhas's avatar
Matt Mascarenhas committed
28
    cinera test.hmml
29 30 31 32

This simply generates an HTML file (and updates `cinera_topics.css` if needed)
from `test.hmml` and outputs to `out.html`

Matt Mascarenhas's avatar
Matt Mascarenhas committed
33
#### Project Edition operation
34

Matt Mascarenhas's avatar
Matt Mascarenhas committed
35
    cinera -p ProjectID
36

Matt Mascarenhas's avatar
Matt Mascarenhas committed
37 38 39 40
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).
41

Matt Mascarenhas's avatar
Matt Mascarenhas committed
42 43 44 45 46 47
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
48
    -R Root URL, corresponding to the Root Directory (optional if the Output
Matt Mascarenhas's avatar
Matt Mascarenhas committed
49
       Base Directory resides in the Root Directory)
50 51 52
    -c CSS Directory, relative to Root
    -i Images Directory, relative to Root
    -j JS Directory, relative to Root
Matt Mascarenhas's avatar
Matt Mascarenhas committed
53
    -b Output Base Directory, location of the table of contents / search page
54 55 56 57
    -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
58

Matt Mascarenhas's avatar
Matt Mascarenhas committed
59
#### Templates
60 61 62

Valid tags:

63
- `<!-- __CINERA_PROJECT__ -->` _the project's full name_
64 65 66
- `<!-- __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_
Matt Mascarenhas's avatar
Matt Mascarenhas committed
67 68 69 70 71 72

*Index Template*
- `<!-- __CINERA_INCLUDES__ -->` _the necessary `.css` and `.js` files_
- `<!-- __CINERA_INDEX__ -->` _the table of contents, and search functionality_

*Player Template*
73 74 75 76
- `<!-- __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_
77
- `<!-- __CINERA_PLAYER__ -->` _the player_
78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101
- `<!-- __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 title of the video, excluding numbering_
- `<!-- __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.
102 103 104

#### Arguments

105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193
    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)
194
        -v
195 196 197
            Display version and exit
        -h
            Display this help